Explain how to document an activity's codebase

[davelab6]

The developer docs should provide

• a guide to an activity's codebase should best be documented;
• examples of 3 activities with great code documentation;

See 2016-June [Sugar-devel] What to use for documenting new sugar activities? thread for discussion

[vipulgupta2048]

@quozl What do you think? We will be going through so many activities in the project (Migration of Activities from wiki to git). We can develop a wireframe or a proposed format for new activities. This helps in making documentation of future activities more consistent and easier to understand by users and developers alike. Also, the parts that are necessary to include in the documentation. A clear format always helps.

We can add a format link here which developers can loosely follow and implement.

[quozl]

Sorry, I don't remember which of the projects you refer to,

We have a severe lack of activity maintainers; developers who follow the two checklists in Contributing - Modifying Activities. I'm loath to demand anything more of these developers, such as defining standards for documentation of an activity, because these standards tend to consume their time without reward. It isn't likely that potential activity maintainers are hindered by a lack of documentation or standards. If there were such potential maintainers, they would be asking questions which reveal their need. We aren't seeing such questions on sugar-devel@ or IRC or GitHub.

However, that said, there are two things relating to good documentation to mention;

• the README.md file, see especially those in Speak, Browse, and Memorize activities. Compare with the Clock activity,
• the use of Sphinx in sugar-toolkit-gtk3 for automatically generating documentation from code using docstrings hosted on https://developer.sugarlabs.org/sugar3 . Compare with how popular Python modules hosted by GitHub use similar tools to build documentation into the readthedocs infrastructure. Good idea for libraries, but not very useful for activities.