[ros-users] [Discourse.ros.org] [Quality Assurance] Documentation for maintainers
ros.discourse at gmail.com
Tue Jan 30 08:07:17 UTC 2018
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](https://github.com/git-afsantos/haros) is working on after-the-fact model extraction from sources. Something similar - but a bit more low-level - is [roswiki_node](http://wiki.ros.org/roswiki_node) by @DLu. Lacking any MDE tools, recovery after-the-fact may be a strategy that can help reducing effort.
[Visit Topic](https://discourse.ros.org/t/documentation-for-maintainers/3838/2) or reply to this email to respond.
More information about the ros-users