Proposal: Focus on how to write good documentation in a readme first, then wiki-like tools like sphinx.

[joelostblom]

Proposal

Focus on how to write good documentation in a readme first, then wiki-like tools like sphinx.

Background

For documentation, focus on how to write good documentation in the readme (this could incude what else to put in a readme such as contrib guidelines etc, unless we're already covering this elsewhere). Include more advanced doc utils such as sphinx after the readme. The motivation is essentially that a readme is appropriate for the package complexity that we're describing and it is better to encourage students to write simple documentation than to have them discouraged by slightly more complex doc tools. See point 5 in multiple comments in https://github.com/merely-useful/merely-useful.github.io/pull/341 for details.

Pros and Cons

Pro:

• Simple docs are better than no docs
• The concepts will apply to writing more advanced docs so there is little readme specific content added

Con:

• One more section before getting into sphinx
• Could run the risk of most students never exploring more advanced tools (but I actually think that is a pro, it most likely means that a readme is sufficient. I would imagine that there are few students capable of learning the skills needed to develop a package advanced enough to require wiki-like docs, but not also be able to learn how to create wiki-like docs, and we will stil provide the basics for these .)

[joelostblom]

Passed on the meeting today