Chapter on how to write documentation for a project

[pgadige]

Summary

Write a short chapter on writing minimal and complete project documentation. The chapter will be a useful guide for project owners to get started with writing documentation for their projects.

Discussion Points

List of tasks:

1. Identify a pattern across documentations of commonly used scientific packages like matplotlib, scipy, numpy, bokeh, xarray
2. Briefly explain (in 1 or 2 sentences) the purpose of each documentation element found in the above pattern
3. Design a generic project documentation template (or outline) for project owners to use in their projects.

Resources

Documentations of commonly used scientific packages:

• Matplotlib
• Bokeh
• Scipy
• Numpy
• Xarray

Who can help?

Collaborators: @malvikasharan

Updates

• discovered the following common elements found in documentations across commonly used scientific software packages

1. Project design
2. First steps guide
3. User guide
4. API reference (or reference guide or API overview)
5. Releases
6. Project roadmap (or development roadmap)
7. Usage examples (or tutorials or demos)
8. Community
9. Troubleshooting FAQs

[malvikasharan]

Reference from Greg Wilson: https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1008469

[malvikasharan]

Fab example from Rachel: https://programmer-rachel.medium.com/

[bouweandela]

This looks related to #879.

[amangoel185]

Working on this issue for the November 2022 Book Dash. Collating the resources and updates here:

Title

Documentation

Guide

Guide for Project Design

Resources

• https://documentation.divio.com/
• https://diataxis.fr/

Draft

documentation.md

Updates

• Write chapter outline
• Add material to the chapter
• Combine materials into a readable chapter
• Proofread
• Create PR and link in the comments
• Request reviews
• Address reviews
• Merge to main branch

[malvikasharan]

Outline

• Landing page: Explain the 'why and how', also explain what your chapter covers (overview: project documentation chapter highlights, Data documentation and metadata chapter, Technical document)
• SC1: Technical Documentation
• SC1: Language and Platform
• SC1: Workflows and resources: what process you can take (pandoc) - invite contribution