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 :slight_smile:)? 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.
---
[Visit Topic](
https://discourse.ros.org/t/documentation-for-maintainers/3838/6) 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)