Growing issue with ROS Documentation

[AbhijithGanesh]

Growing issues with the ROS 2 documentation ecosystem

I previously brough this issue up for the ROS Noetic where the documentation can be improved.

This has only further worsened for ROS2, There have been several pitfalls

Key pit falls:

• Poor SEO for Iron, most documentation points to humble or foxy
• Poor full text search responses (Algolia would really help here)
  Example 1:
  
  

Example 2 (I’d understand why DL frameworks like Torch isn’t documented but this is not the way to go)

• Lack of migration guides
• Lack of instructions on how to mitigate failing ROS2 builds for ecosystems beyond Ubuntu/Debian
• Poor explanation of how to use it in the cloud
  
  

With all these points in hand, I strongly feel there is a stronger need for a more consolidated effort that focuses on documentation

[AbhijithGanesh]

Continuing the discussion from Why don't we use Docusaurus / Nextra ? A propsective idea:

@clalancette

Given that ROS 1 is only supported for the next 1.5 years, I don’t think we should spend significant time on restructuring the documentation.

For ROS 2, the Sphinx output already looks extremely similar to Nextra or Docusaurus, so I don’t see a very compelling reason to change tools there. Of course updates to the contents are very welcome.

The use of tooling is secondary but these systematic issues really hamper the community

[clalancette]

@AbhijithGanesh

The use of tooling isn’t secondary but these systematic issues really hamper the community

Can you explain why? Most of the issues you bring up have to do with either SEO or the content, neither of which will be improved by changing tooling. The one that might be helped is the internal searching.

[AbhijithGanesh]

Apologies, I was supposed to type

Tooling is secondary, but these systematic issues really hamper the community

[clalancette]

@AbhijithGanesh

Tooling is secondary, but these systematic issues really hamper the community

OK, that I agree with

[AbhijithGanesh]

is there a Documentation WG/Technical Docs WG who look after this?

[AbhijithGanesh]

I am sure we can integrate algolia into sphinx as well

Ref:

GitHub - algolia/sphinx-docsearch: Add Algolia DocSearch to your Sphinx...

[clalancette]

@AbhijithGanesh

is there a Documentation WG/Technical Docs WG who look after this?

Not that I know of, but maybe @kscottz can chime in. If not, I think it would be a worthwhile working group to have.

[AbhijithGanesh]

Do we have a monthly townhall for the entire community ? I think at this point we should, as there are multiple WGs and we need to consolidate our efforts. ROS2 has too many breaking changes which will deteriorate the ecosystem further if not acted upon swiftly

[MiguelCompany]

I think this might be handled (at least partially) in the production WG. There are at least plans to improve technical documentation.

[AbhijithGanesh]

Shouldn’t this be more than a production WG thing ? Because if you consider major FOSS projects like Kubernetes , they have their own Technical Writing SIG

[Katherine_Scott]

I previously brough this issue up for the ROS Noetic where the documentation can be improved.

This has only further worsened for ROS2, There have been several pitfalls

I don’t disagree. I would like the situation to improve. We need more developers dedicated to putting in the work to improve the documentation. What many people don’t seem to understand is that the docs aren’t going to improve without community contribution.

Right now, internally, I’m working on a plan for moving over documentation from the ROS Wiki to docs.ros.org, on top of the myriad of other things I have to do on a daily-basis. Part of that process is figuring out what changes we need to make to docs.ros.org to facilitate that transition. That plan isn’t ready yet for a general audience, but it is something we’re working on.

@AbhijithGanesh

Poor SEO for Iron, most documentation points to humble or foxy

SEO pointing to the LTS ROS release is a feature, not a bug.

Poor full text search responses (Algolia would really help here)

Agree, if you feel so strongly about what technology to use, and the necessity of this feature, why not send over a pull request?

• Lack of migration guides

You mean these? Or the Gazebo one we’re releasing today? I also sent over this pull request last night for migrating wiki docs.

• Lack of instructions on how to mitigate failing ROS2 builds for ecosystems beyond Ubuntu/Debian

I think we’re pretty clear on what operating systems are supported. Windows support could improve, but Windows is also a very small percentage of the community. Improving support beyond the current Tier 1 operating systems is longer conversation.

Poor explanation of how to use it in the cloud

We’re not cloud compute vendors, and I would be reticent for us to advocate for one cloud over another. More to the point, I don’t think cloud-specific documentation belongs in the core ROS documentation, it belongs in the documentation for the specific cloud service provider. Why not request such documentation from your cloud vendor?

Having said that, there are other groups making progress on this front.

With all these points in hand, I strongly feel there is a stronger need for a more consolidated effort that focuses on documentation

Great! I think most people agree. Are you simply pointing out these issue or do you have a proposal for how to improve the situation? A specific proposal, with a call to action, usually works well for motivating people.

I would really appreciate it if people made the choice to volunteer to help, or clarify the current sitution, instead of simply complaining about the near infinite project back-log. We’re all on Discord and quite friendly.

[AbhijithGanesh]

As for the support for operating systems, I am not complaining about windows as such, I am just saying we need to have a guide as to how to build. I remember seeing a Fedora build from source. Recently there was this discourse thread about RISC-V

Installing ROS2 humble on RISC-V Ubuntu

Hi all! I’m new to ROS 2, and I’m trying to install it on a RISC-V Ubuntu 22.04.3 using QEMU. I’m following these isntructions: https://docs.ros.org/en/humble/Installation/Alternatives/Ubuntu-Development-Setup.html The main issue is that ROS repository does not support riscv targets, and I wonder how difficult it is to add support to this architecture or how to build it from source without using ROS repo. Can anyone send me a few pointers to achieve this?

It’d be prudent to add support/guides for source installs like this

[Katherine_Scott]

There isn’t a docs working group. If someone is willing to make a commitment to do this it would be great. Having said that, running a working group is a real, serious, commitment, and we should have a conversation before actually proposing such a thing.

[JRTG]

@Katherine_Scott

We need more developers dedicated to putting in the work to improve the documentation. What many people don’t seem to understand is that the docs aren’t going to improve without community contribution.

I’d rather say you need more technical writers putting in the work to improve the documentation. They are a very different profile than developers.

@Katherine_Scott

A specific proposal, with a call to action, usually works well for motivating people.

That requires someone to take the lead. This is a general issue, ROS 2 lacks project governance. I don’t see why the OSRF does not take on that role.

[gbiggs]

@JRTG

I’d rather say you need more technical writers putting in the work to improve the documentation. They are a very different profile than developers.

We are aware, and we actually used to have a full-time technical writer on staff. Unfortunately we could only afford one at that time (and as of today we can’t afford any) and a single full-time technical writer is nowhere near enough to handle the backlog of documenting ROS, Gazebo, Open-RMF and the infrastructure that supports them without community contributions doing the bulk of the work.

@JRTG

That requires someone to take the lead. This is a general issue, ROS 2 lacks project governance. I don’t see why the OSRF does not take on that role.

ROS 2 has project governance. @clalancette is the project lead, with 100% of his work time generously donated by Intrinsic. He leads a group of core contributors, and is doing a stellar job, in my opinion. You can see many of the various tasks they’re working on at the project boards.

Build software better, together

But there’s only so much that a project leader and a group of core contributors and project management can do. Ultimately, ROS 2 is an open source project, and community contributions should make up the bulk of development. That includes documentation. Besides, no matter how much someone tries to direct volunteer developers (which is all that all contributors are, ultimately, including the core contributors), they’re going to focus on what they want to focus because the project leader is not their manager and has no contractual power over them.

If you see something missing from the documentation, add it and send in a pull request. If you find an error in the documentation, fix it and send in a pull request. If you can think of a way to improve the documentation infrastructure, do it and send in a pull request. This doesn’t require a project leader to tell you to do it, nor does it require someone to invite you to do it.

[gbiggs]

@AbhijithGanesh

I am just saying we need to have a guide as to how to build. I remember seeing a Fedora build from source.

It’d be prudent to add support/guides for source installs like this

We have guides on how to build from source on our supported platforms:

• Ubuntu (source) — ROS 2 Documentation: Iron documentation
• RHEL (source) — ROS 2 Documentation: Iron documentation
• Windows (source) — ROS 2 Documentation: Iron documentation

We are happy to have community-contributed guides to building on other platforms, but we are not going to try and maintain them, the community needs to do that. This is because there is no end of additional platforms that people might try to build ROS 2 on. Which ones do we choose? This question is why we have a supported platforms list.

If you have an additional platform you know how to build ROS 2 on, and want there to be a page in the documentation on how to do it, then send in a pull request adding that page - but also please commit to helping keep it up to date as that platform changes and additional releases of ROS 2 are made.

[CursedRock17]

I keep seeing posts like this which ask for more intense, specific documentation, similar to the things in the original second example. When it comes to open source, the target audience is everybody - with each person having their own certain objectives. Generally speaking, it’s almost impossible for an organization to cover everything all at once, that’s why it’s community orientated. Obviously it’s great to have solutions already made, then all it takes is a little bit of tweaking or API usage to solve your problems, but sometimes they’re not made already, so you have to make them yourself; it would then be your goal to spread the information that you needed.

We’re not cloud compute vendors, and I would be reticent for us to advocate for one cloud over another. More to the point, I don’t think cloud-specific documentation belongs in the core ROS documentation, it belongs in the documentation for the specific cloud service provider. Why not request such documentation from your cloud vendor?

^ Exactly this, unless it is in its own repository created by the community, somewhere accessible, then it would come from the direct source you want to use.

I will concede that the main issue here is actually keeping that information together, we have ROS Index but unfortunately it doesn’t cover every single repository in existence which uses the ROS 2 API. Though, I have no clue what solution would actually work, other than making a giant collection of ROS APIs, in which the community would have to add each and every one. For instance, all these repositories:

• ROS2_cookbook
• ORB_SLAM3
• BONXAI

Have great API usage and guides that pair with ROS 2, that are very clearly defined, they just wouldn’t show up in a basic search in the ROS documentation (which is fine since they are all third party). I don’t know if I’m missing the point or veering off topic, but I don’t believe most basic ROS 2 documentation is misaligned or frustrating, nor is it necessarily OSRF’s job to keep advanced usages in one spot. That being said, if there are any big documentation changes that need to be made, I’m definitely willing to help, there’s no large search for anything like that though right?

[gbiggs]

@CursedRock17

I don’t know if I’m missing the point or veering off topic

I don’t believe you are. While we should and do strive to provide the best core and beginner documentation we can with the resources we have, and would love to have more resources provided by the community, the number of combinations of use case and utilised platform and software version is uncountable.

It’s much the same as when you need to do something on Linux. You don’t go to “the one true documentation site” expecting your specific combination to be there. You start in a search engine and look for someone who’s written about or documented something similar enough that you can base your solution on.

[doganulus]

@gbiggs

Ultimately, ROS 2 is an open source project, and community contributions should make up the bulk of development.

Why is the bulk of the TSC not composed of community contributors, then? Why do companies not generously donate FTE for documentation tasks?

Sorry, this is the question the OSRF needs to address before complaining about the community and volunteers. As I have written many times, this is the reason for the existence of the Foundation. Yes, this is a governance problem.