For instance, all these repositories … 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).
Thanks forrmentioning Bonxai (I am the author) as a good example, but WHY would the ROS documentation mention Bonxai?
Bonxai (as hundreds more projects) are independent of ROS and Open Robotics, and it is great that we have a decentralized ecosystem of open source software.
On the other hand, we do have some popular libraries that MIGHT be considered “kind-of-official” (but they are not), such has Nav2, Moveit, PCL, BehaviorTree.CPP, etc.
But these frameworks are large enough to need their own documentation.
I am going to say something different: people don’t read documentation.
I received a lot of Github issues related to BT.CPP, that could be avoided by reading the tutorials. Empirically, it seems like no one read futher than tutorial 3.
Talking about the official ROS documentation, it makes me sad that people rarely know about Components, when they are clearly explained and they are great.
We need documentation as to how to interface them with “generic” / “agnostic” cloud tools, I certainly am up for contributing to this but I really donot agree as to why we should request cloud service providers for the same. This is an activity within the ROS2 community that needs to be solved and not outside. I necessarily donot understand why someone like AWS or Azure should provide documentation about how to run ROS2 in a Kubernetes Cluster. I am sure Christine from Asimovo would agree to this (as she’s related to the Cloud Native ecosystem)
Development and Documentation are two different processes, documentation is a a problem of a different scale. We need a Dedicated team/effort from the community to write better docs (PS: I am up for contributing to this) but if we’re going to shift the responsibility to the developers/group leaders like @clalancette , we’re doing grave injustice to their work.
I strongly disagree with this. People who are new to ROS heavily depend on documentation as there are not many “external resources” to refer to except these documentations.
But if they’re brand new to ROS why would they need to have extensive documentation on advanced issues, like the cloud. Either they don’t understand ROS yet, or don’t understand the cloud enough to implement ROS in any way, shape, or form. I think internet searching for any large scale project is the way to go, it’s just whether or not we can compile all these resources together - which doesn’t seem valuable to extent of the Open Source organization.
I brought the issue up so that we have more support. It’s unfortunate that it’s being interpreted as compiling “all” resources together. That is clearly not the objective. Infact the objective was to ensure that there is a consolidated SIG for docs/technical writing
Documentation and governance, my two favourite topics!
The first ROSCon where documentation was flagged as an area for improvement was…the very first ROSCon This is not a new situation, nor is it unique to the Open Robotics open-source initiative. And, every day ROS is used in more and more unique use cases, by a wider and wider variety of users, and with a growing spread in foundational requirements. Thus, saying ‘we need better documentation’ without more specific examples as to where is basically noise. Hence, the requests for clarity/contributions.
The degree of decentralization which has occurred since the early days has been incredible. But, the vast vast majority of ‘companies’ are not (yet) making strategic decisions to ‘allocate resources’ and then asking Open Robotics how those resources should be allocated. Right now, what is far more common is that developers like, well… developing OSS, and convince their own companies to let them do so. With few exceptions, those developers do not appear to like writing docs, and that’s what we get. Look at the TSC meetings - those are filled with members of the community, and they’re not exactly filled with enthusiasm around docs. If someone wants to run for community rep or the like with the entire platform of ‘I’ll make the docs situation better’, I’ll vote for you at least
For topics like “cloud tools”, that’s a specific case of the general case above. There are people at AWS who work on/with ROS every day who are members of the community just as much as everyone else is, they can help too!
In the end, Open Robotics can guide and encourage and document with 100% of their time instead of writing code, but as you’re all noticing, if every community member in the end decides to develop instead of document, there’s not much Open Robotics can do about it. Even efforts like ours at Clearpath Robotics to maintain sites like this are a drop in the bucket.
The reason for the existence of the Foundation is “to support the development, distribution and adoption of open source software for use in robotics research, education, and product development”
By all metrics, we have and continued to succeed massively at this. Hence why we could use better docs
I can assure you that the moment we have an organized community effort, oss devs will flock to contribute as documentation contributions are relatively easier compared to “core technical” contributions
This is clearly an organizational issue
Companies do not allocate resources unless you ask them and give them something in return. If the TSC member companies do not contribute documentation, then they violate the TSC charter. As a board member, it is your responsibility to track such requirements. Otherwise, you are a part of the governance problem.
I am quite aware of how companies decide to allocate resources, yes. I am also aware of what my responsibilities are (and are not) with respect to Open Robotics.
Also, given your awareness of my (very public) background and history, implying otherwise is bordering on a personal insult and I’d ask you to refrain for the sake of returning to constructive discussions on the topic at hand.
A constructive discussion is our primary goal. Therefore, let’s stop blocking every discussion in this forum with an argument of lacking resources and using open-source as an excuse for low quality.
Like the NYPD which cannot complain about the high crime rates in Manhattan, the OSRF cannot complain about the lack of organization/coordination and resource finding. This is the task of the OSRF. As the organization, you cannot complain about the lack of them. Please don’t be offended when this is reminded.
This was not my wish, yet every time I hear the same non-constructive arguments of resource lacking. If resources are lacking, then go and ask member companies before poor students. I hope you gonna take the necessary precautions so that these arguments are never used by the OSRF.
What would be most constructive in this topic and related working groups would be a common understanding of what should make up “core” documentation, who the audience is, what the current gaps are, and what is needed to close those gaps. If members of the community can agree on those points, then we will have the beginnings of real progress.
This is not a new situation, nor is it unique to the Open Robotics open-source initiative. And, every day ROS is used in more and more unique use cases, by a wider and wider variety of users, and with a growing spread in foundational requirements. Thus, saying ‘we need better documentation’ without more specific examples as to where is basically noise. Hence, the requests for clarity/contributions.