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.
If you do not want to receive messages from ros-users please use the unsubscribe link below. If you use the one above, you will stop all of ros-users from receiving updates.
______________________________________________________________________________
ros-users mailing list
ros-users@lists.ros.org
http://lists.ros.org/mailman/listinfo/ros-users
Unsubscribe: <
http://lists.ros.org/mailman//options/ros-users>
(text/plain)