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.
Replying here as a developer: for me the biggest blockers here are time and effort.
It’s not that I don’t want to write such high-level overview documentation - I have it already anyway, if only on a whiteboard or piece of paper, it’s the time and effort it takes to get it into a usable and digestible form and then publish it somewhere.
Doxygen and Sphinx (to name some examples) can be used to create really nice documentation, and some of it is highly automated, but anything at a higher abstraction level than functions/methods/classes I believe is still the responsibility of the developer.
I know this is a bit of a lame response / excuse (as it’s always “we didn’t have time”), but unfortunately it seems to be a reality that should probably be dealt with.
Perhaps tooling to support this process (both automating creation as well as publication) could go a long way.
I know the author of HAROS is working on after-the-fact model extraction from sources (see last slides of this presentation). Something similar - but a bit more low-level - is roswiki_node by @DLu. Lacking any MDE tools, recovery after-the-fact may be a strategy that can help reducing effort.
Replying here as developer: documenting is no fun!
Replying here as tester: wtf shall I expect if I shall design or write test for that?
Solution: Let your boss decide what to prioritize
Real solution: We recently had that discussion as well. Usually both roles care mainly about the public high level view (in the first case its because you forgot what you designed/implemented half a year ago, in the second case its even worse because you could know nothing about the package yet). Then it depends on how broad the public API and how complex the public behavior is. If its quite narrow it shouldn’t be a problem to “quick and dirty” sketch some high level diagrams (whatever lightweight UML like format suites the situation) with some GUI tool (usually faster than using dot or something similar). I like the arc42 template (some example) because it encourages to use “business context” diagrams as well.
I get the tongue-in-cheek, but I believe the problem is even bigger here: ideally a solution works both when there actually is a boss, and when there isn’t.
The latter is – at least for now – probably still more common in the large, federated and sometimes completely unconnected ROS developer population.
How about we start with something low-effort such as adding hand-drawn design diagrams + annotations and some bullet points but allow the developer to achieve anything above this level (which could be UML )? It’d obviously be better if the diagrams are drawn on a tablet compared to clicked off a whiteboard, but we should take whatever we can get without stressing the developers.
There is literally no need for generating diagrams using dot or in LaTeX, but some format of documentation which keeps up with code and doesn’t lag behind is preferred since this isn’t describing the API usage, but the design which is prone to changes (the level which Sphinx and Doxygen don’t generate automatically)
As for time and effort, it’s a double edged sword. No documentation (and tests) saves development time till the project exceeds an abstract threshold of complexity, and then lack of documentation costs time. Maybe we can start by working on projects the developers are already feeling the effects of lack of documentation?
I’m not sure where we can publish such images (not because they are dirty, but rather ros wiki vs github wiki)
Wishful thinking: Maybe someone can improve Pix2Code so we can use the images to create UML diagrams from images.
I don’t want someone to get this wrong. But I think in a company neither the “developer” nor the “tester” role (independent of the fact if these roles are executed by the same person or not) has the authority to decide something like that on some bigger scope (e.g. company scope). Usually company guidelines which are commonly agreed on handle decisions like that (after considering possible implications).
Speaking as a community member I would consider (1) package guidelines before (2) working group guidelines (for several packages) before (3) general community guidelines as starting point to loot for information like that.
IMO, this is the correct order. Do you have any packages to start emulating the guidelines from? It would be really nice to have a few (2) or (3) level guidelines as a starting point for new packages and developers.
I was working today to kick off http://wiki.ros.org/Quality and I was reading this wondering what should be the first tutorial to move to our not-yet-announced place-to-go for quality resources.
Reading the above, I was thinking whether there is a guide describing how to document a package? Is there? I found these:
None of these explains or hints what is a good ROS package documentation. What questions should a package author answer in his wiki entry? What are the good examples? What are good style elements for documenting a package?
There is a lot of outdated information there as well that would be good to clean up. All the Stack references. And a lot of the workflows and Process pages are mostly out of date/unused since they are pre github etc.
In general for good examples, I’d recommend looking at core packages.
)? It’d obviously be better if the diagrams are drawn on a tablet compared to clicked off a whiteboard, but we should take whatever we can get without stressing the developers.