[ros-users] [Discourse.ros.org] [Quality Assurance] Documentation for maintainers

[tyagikunal]

Most of the documentation for ROS packages falls under these broad categories:
* In-code comments // Hello there
* Docstring (or generated by docstrings) /** @General Kenobi ! **/
* External (eg: a webpage, say a wiki, or ros website or gitbook or readthedocs or something similar)

Mostly, people use them to answer their Why, What and How questions, and **this is sufficient for a lot of developers**. However, it is not sufficient to encourage people to join a package as a maintainer. For that, people need to understand how the code is designed and, why is it the way it is. If we reduce the amount of time a person has to grok to understand the layout, it will take less time for the person to contribute patches which wouldn't cause issues a release or two down the lane. Most of the contributors who start with small bugs face the issue of steep learning curve for a foreign code base.

This requires a documentation somewhere on the level of Docstrings, but dealing more to the concerns of a maintainer than a user. This might even ease changing maintainers as well as maintain packages which become orphans. This practice is already popular in the wider open source community.

As always, I'm eager to know your views on the topic and am open for questions and discussion.





---
[Visit Topic](https://discourse.ros.org/t/documentation-for-maintainers/3838/1) or reply to this email to respond.