Product SiteDocumentation Site

Appendix A — Notes for Instructors

A.1. Explaining the Code

This chapter relies upon a wiki installation. Since we are teaching true FOSS participation, it's important that we don't think of the work as throwaway. In particular, the work done for documentation includes taking notes for the class, and those have value of team documentation throughout the class and beuond. For example, future classes can learn from and build on the wiki work done by previous classes, while still conducting a useful exercise. Templates can be borrowed, naming conventions borrowed, while writing new content.
  • Wiki needed, recommendation: MediaWiki is well suited.
  • You may want to run this chapter early on so the class is self-documenting from the beginning.
    • Some of the exercises are best done as part of other exercises, such as documenting the obtainment, testing, and version controlling code.

A.1.1. Teach two important sections ASAP

Two of the sections in this chapter are useful for early in the class, both the information and exercises. The exercises are used throughout the class, so are useful when taught early or first.
  • Explaining the Code - Introduction is useful for explaining how the FOSS methodology is useful in non-code situations, which is an essential point to understand. The exercise in this section is to do good code commenting and developer documentation for any code developed in this class. This is a useful exercise to begin early in the class.
  • Explaining the Code - Documenting technical and community proceedings also shares a useful FOSS developer skill that is non-coding. The exercise is to work as a class to document the class, and so is most useful when it is begun at the earliest opportunity in the class.
Subsequent editions of the book are likely to refactor this content and move it to an earlier place in the textbook.