5. Documenting software projects

The objectives of this tutorial are to familiarise yourself with:

• principles for creating good documentation;

• plain text markup languages commonly used for writing documentation (Markdown and reStructuredText);

• tools for processing plain text documentation and generating output in html or pdf formats (Sphinx);

• online services for hosting documentation (ReadTheDocs); and

• methods for contributing to documentation.

Contents:

• 5.1. Writing effective documentation
• 5.2. Languages
• 5.3. Documentation generation tools
• 5.4. Creating new documentation with Sphinx
• 5.5. FAQs
• 5.6. Hosting documentation
• 5.7. Updating documentation
• 5.8. Documenting source code (TBC)