Growing issue with ROS Documentation

General
,
42

Do you want to start one?! I’m sure folks would love that! Be the change you want to see in the world! Feel empowered, I think everyone’s on board with someone that wants to champion that! If you want to spin one up or the education working group and run that, I’m sure I/we can help make that happen.

I actually really love that idea. It should not devolve into only a complaining session, but a time for everyone to get together could be awesome if we could organize it well enough to deal with the huge mob of people. Maybe quarterly instead… @gbiggs what do you think about that?

This is not the way that the TSC is setup (currently). TSC members have to contribute FTEs but it is not specific to what they work on, as long as its a ROS core capability. That’s how we get the variety of things from Nav2, to ROS 2 Control, to rclcpp improvements, and beyond by various organization that have their own projects and programs going on that touch different parts of the ecosystem. The choice to prefer their time, as {control, build system, DDS, cloud} experts, to doing basic ROS 2 documentation is not objectively the best use of their time and limited resources, necessarily. Maybe it is, maybe it isn’t.

Note that alot of TSC members do contribute already to documentation. Samsung (when it was on the TSC) had a technical documentation writer on staff working First Time Robot Setup Guide for Nav2 - that was very generous and above the strict requirements. I see the likes of Sony, Bosch, and Foxglove also represented on the main docs website source (in far excess of the occasional bits from me) as regular contributors. Its not like TSC and other ROS-based companies aren’t contributing already.

In my opinion, we need a group of folks that want to own this issue and push progress on it. Little happens without personal responsibility being taken by someone to make the changes they want to see in the world. Until a working group or a champion appears that wants to take the effort on themselves, the resources exist to make incremental changes approaching improvement at a speed that is apparently insufficient to many’s likings. I think other folks in this chat clearly laid out that OSRF does not have the resources or tools behind it currently to be that champion - but perhaps that could change in the future. Make sure to ask your companies and organizations to donate to the Foundation to support documentation. Its an investment in your own problems and perhaps then @gbiggs can have technical documentation writers on contract / staff.

Unfortunately just like many of your companies and organizations, OSRF doesn’t have infinite resources and time. They have to pick and choose with what they have to do the most good. More resources make for more options – or have a community member step up to take the lead. I’d do it if I didn’t already have an infinite backlog in my Nav2 + related projects already :smiling_face_with_tear:

An Ode to @doganulus

I guess here nor there, but does this militant attitude to everyone work well for you? I feel like every time your name pops up in a thread you’re calling someone something mean. I’m definitely not blameless in some threads of getting a little worked up, but cranked up to 11 seems to be your default state when you engage with folks working to improve things – which causes the entire thread to veer off track and results in far lower likelihood of the changes you want being made. Maybe you have a point, maybe you don’t, but when you treat people that way consistently, it stops mattering and your thoughts are dismissed.

I’ve worked around this for several of these threads and looked past the specific language to your higher level points, but jeeze man, the most friendly advise I can give you: Please cool it.

12 Likes
43

Please @smac, I cannot accept this. And I would have to ask an apology if you insist on your particular choice of words. I am particularly careful about my words. Please tell me if any of my words are factually wrong, and I will happily correct them. Usually, here, I call for a particular type of behaviors on the forum, which has been consistent during the last two years. These behaviors I call for gatekeeping, student bashing, arbitrary forum moderation, tech-bro jokes, and excessive sugarcoating about ROS. These behaviors are ignored by the moderation because they are from the “inner cycle” of the ROS community. The rest are called militant or immediately labeled as noob. This is unacceptable in forums; I am not shy about calling it out. This type of selective moderation only strengthen my point.

1 Like
44

A couple of notes on documentation (I’ve been working on docs lately quite a bit):

  • The education WG might be a good place to start initially - because in talking with a number of educators/researchers - ROS 2 documentation is one of their bigger hurdles in migrating from ROS 1
  • I’ve recently ported the image_pipeline docs from the Wiki to the ROS 2 API docs (this is the recommended workflow for packages in ROS 2) - it’s still a bit of a challenge - but Kat’s PR linked above will definitely help.
  • My biggest take away from porting those docs is that rosdoc2 and index.ros.org need some love - they have quite a few open tickets and not a lot of active work going on. Things like this might be the sort of contribution for developers who don’t consider themselves technical writers (or don’t enjoy writing).

Some examples:

11 Likes
45

In regards to the “docs vs tutorials” datapoint, where it was conjecture “noone reads further than tutorial 3”:

I will first fess up that I dont remember my own personal read/not read in that area. however, I will mention an important point of interest, given that I’ve been through many other tools/frameworks/tutorial combinations:

Sometimes thats due to the audience.
Most of the time, though, it’s due to the creators of the tutorials. Whether that be the organization of them, or the choice of topics, or that the tutorials are just poorly written.

There have been multiple projects where I have found the tutorials highly annoying to follow.
There have been multiple projects where I have found the tutorials just not relevant to what I wanted to do.

Also, if some project has 10 tutorials, I’m not going to go through them in order. I’m going to jump to the specific one(s) that seem most relevant to me, and ignore everything that seems irrelevant.

I guess all this is to say, “yes, the foundation needs a tech writer again really badly. Please get a good one, and point him or her at the tutorials to make sure those are solid first!”

(the tricky part here, is that for that area, you need a techwriter that is also a good coder. Almost as hard a trick as finding a good coder that is also a good manager :stuck_out_tongue_winking_eye: )

4 Likes
46

Perfect! I always liked the structuring of the image_proc documentation, and it’s great to see that ported to ROS2! Now what’s the magic to convert the ugly README.md’s of my packages (camera drivers etc) into the same beautiful format as image_proc? I’m certainly willing to put in some time to get there.
And another question: are there some guidelines (like a REP) to follow regarding the order in which material is presented (first parameters, then topics, then services etc)? It does help to have some uniformity across packages when it comes to documentation.

4 Likes
47

Unfortunately, that first ticket I linked is the one that basically says there is no defined format for the docs - I just kept the same order as the ROS 1 wiki. Kat mentioned an html->rst tool in her PR that I’ll have to try out - not sure how different it would be from what I hand ported.

The key to the docs is basically adding a doc folder and add some restructured text in there - see this PR for an example.

I think adding some additional suggested style information to Kat’s new tutorial might be the way to go (a REP is probably going to be too contentious for documentation formatting to ever get it through the review process)

1 Like
48

A couple of years ago, I spent some time learning rosdoc2, hoping to contribute to documentation, as that has always been a frustration of mine working with ROS. But I got discouraged because for some reason the blocking python pull request languished for months without being landed, so I moved on to other things.

But it seems like the reviewers have been more active there recently, so I am thinking about getting back into it. But I am looking at rosindex instead, as that seems to be the more active project. Just for laughs I tried pulling in the data from download counts to see if that would be useful, you can see that result at ROS Packages if you want.

I would certainly be interested in participating in any documentation working group.

2 Likes
49

Thanks for

Thanks for bringing this up @rkent. Us coming together to discuss how to take it further will really aid us improving our docs. On a different note. Let us stop expecting only the “TSC members” to contribute. We as a community are equally responsible. So let us use the #education-wg and start making documentation better

2 Likes
50

I was told using Education - WG was a good alternative instead of starting a new WG. Let us see how it goes with Education WG else, we can deliberate further as to what should our course of action be.

Key Take aways so far:

  • Need for Monthly TownHall
  • Contribute no matter who you are (TSC or not)
  • Contribute via Education WG’s
  • Improve User Experience via docs
  • Centralize non-technical information via docs too
51

I looked at your PR that adds the doc directory … will the ROS2 build farm then automatically generate the documentation off of the “doc” directory and put it on some web site that is indexed? No additional configuration needed in e.g. “CMakefiles.txt”?

52

Generally yes - you need a properly configured doc/conf.py and then you’re good to go (technically, you need to also have some code in a reasonable location or the doxygen/sphinx will fail and then nothing generates - if you don’t meet that requirement, it gets messy - see the image_pipeline for an example where I had to define a rosdoc2.yaml - and play with the config. I’m planning to add some notes in the ros2_cookbook - the solution is somewhat hacky, so it may not ever end up in the rosdoc2 readme).

I’ll definitely be contributing some more documentation around creating documentation - I only finished getting image_pipeline documentation done earlier this week

2 Likes
53

Is any package within ROS off limits? I saw that @mikeferguson has ported off image_pipline

I only finished getting image_pipeline documentation done earlier this week

So could I help with the process? Maybe port over Geometry2 since it has no link to documentation? I didn’t know if we needed to wait as to not cluster the process.

Also to refute claims that OSRF isn’t providing help to the documentation themselves I saw this

54

Great initiative by intrinsic. If we start another debate as to OSRF focuses on this issue or not, then it’ll erupt into a parallel conversation about the governance of OSRF itself. So, instead can we focus on the current topic

55

One minor clarification to your last point - though I’d love for the OSRF to take direct credit for that job posting, that’s an action independently taken by Intrinsic to support the community. OSRF obviously strongly encourages such things :slight_smile:

2 Likes
56

I’ve always found the annual “Answer ROS Questions Like A Pirate” day/week to be fun…

Can we start celebrating “Improve ROS Documentation Like a Technical Writer” week to highlight areas in need improvement, spur some community support, and give some recognition to people making great contributions?

Not suggesting that will solve the need, and I’m open to workshopping the name, but it might be a relatively low effort step in the right direction

4 Likes
57

Yea my bad :laughing: . Would definitely have to agree that an Education WG would be a great place to start branching out, especially if the meeting notes are revealed to the community. That way there’s some form of structure to the way in which we add examples to documentation. I think we can all agree that we want as many examples as possible, it’s just about how centralized we could possibly make it.

1 Like
58

The best thing would be to talk to the package maintainer(s) - as they will ultimately be the ones to merge your documentation changes (since it will live in the source repo). The reason I ported image_pipeline docs is that I am a maintainer on the project.

5 Likes
59

Much needed initiative

60

All I can say is thank you for your service! I feel like you guys are great at managing the community and building a good collaborative environment, great free software for the whole world to use!

It’s a pity that some frustrated individuals let out their anger at you, just because you are a public figure, I guess such behavior comes with the job, but it can still annoying.

@doganulus Please just relax. Step up, be the change you want to see, if you have critique make it positive, constructive and actionable. Just saying things are not ideal isn’t helping anybody, especially if done in an aggressive manner.

6 Likes
61

My company lets me allocate time as needed for me to contribute to ROS 2 in ways that are mutually beneficial to the goals of my team and the ROS community as long as I don’t expose intellectual property. Docs for how to use ROS 2 are the easiest thing to get approval for.

While these contributions are fairly limited on company hardware and billed hours, I tend to also take personal time to contribute many things, including docs, because I care about FOSS and the ROS community enough to donate my free time to improve things for everyone.

For example, the ament_cmake tutorial exists in its current state on humble largely due to the contributions in my free time, and Chris’s willingness to accept them and iterate on best practices. The tutorials on Foxy are much harder to understand than what’s needed. I also contributed a few ament_cmake features that it was sorely missing and blocked some internal packages from using it. The ROS build system is one of the most often complained about items, but I come from teams whose CMake knowledge consists of set() , add_library, and file(GLOB) and don’t even know why you want find_package. Personally, devops and build system are the last thing I want to be working on, but if I can document how to do things and enable others to solve their problems, that’s fantastic.

Another example contribution was the fact that searching gdb on the ROS tutorials yielded zero results, and I want to use GDB all the time. printf debugging is horrible with a two hour cross-compile build. Thus, I added docs on debugging ROS tests with gdb just last week.

I’m not on the TSC, but recognize that improving docs will benefit my team and others greatly. One team I was on thought it would be a good idea to spend time code-generating all the CMakeLists for our packages because it was too confusing to manually maintain or learn, largely because the docs were so bad. Once the docs were improved and the team recognized they didn’t need code generation to work on build systems, we stopped maintaining it. Contributing code to the ROS 2 docs has been a great experience, and pull request reviews are the fastest I’ve seen in any of the ROS repos I’ve contributed to (thanks @tomoyafujita !!)

While I agree with some of the common takeaways and would be happy to join an education/docs working group, I do not agree with your assessment that the TSC owns documentation. Ultimately, I’m more than happy to contribute docs as I find issues.

5 Likes