How can you write better ROS documentation?

由人工智能和领英社区提供技术支持

ROS documentation is an essential part of developing and maintaining ROS projects. It helps users, contributors, and maintainers understand how the code works, what it does, and why it matters. However, writing good documentation can be challenging, especially if you are not familiar with the best practices and tools. In this article, you will learn how to write better ROS documentation by following six simple tips.

此文章中的业界达人

由社区从 8 条内容中精选。了解更多

Lakshmi Sowjanya Chunduri

Robotics Engineer at TCS Research and Innovation Labs
Gerard Kinneen

Help ADHD Coaches & Therapists find Clients | Turn ADHD Coaching Challenges into Growth | With Our Mental Health…
Sudhanva S

Among the early generation of Robotics Engineers in India

1 Know your audience

Before you start writing, you need to identify who your documentation is for. Different audiences have different needs, expectations, and backgrounds. For example, a beginner user might need more explanations and examples, while an advanced user might prefer more technical details and references. A contributor might need more guidance on how to set up the development environment and follow the coding standards, while a maintainer might need more information on how to test, debug, and release the code. By knowing your audience, you can tailor your documentation to their level, style, and purpose.

添加您的观点

Gerard Kinneen

Help ADHD Coaches & Therapists find Clients | Turn ADHD Coaching Challenges into Growth | With Our Mental Health Marketplace.
(已编辑)
举报内容
I focus on clarity and comprehensiveness. What I mean is that I briefly explain my concepts by detailing everything to help future I better understand when I ultimately forget to give myself step-by-step instructions (with examples).

已翻译

赞
Mahdi Yazdanpour

Assistant Professor of Mechatronics Engineering Technology | Robotics | Artificial Intelligence | Brain Computer Interface | Human Robot Interaction | Intelligent Systems
举报内容
To improve ROS documentation, maintain a clear structure with an introductory overview and step-by-step tutorials, supplemented by practical use cases and annotated code snippets. Keep the content up-to-date with version-specific details, foster community engagement through support channels, and provide a feedback mechanism for user input. Ensure accessibility and a searchable format to enhance user experience. This approach aims to deliver concise, informative, and user-friendly documentation, ultimately contributing to the widespread adoption of ROS in the robotics community.

已翻译

赞
Vivek Gurve

?? M.Tech- ARTIFICIAL INTELLIGENCE AND MACHINE LEARNING ?? | PGD-INDUSTRIAL ROBOTICS ?? | B.E- MECHANICAL ENGINEERING ??
举报内容
Understanding your audience is crucial when creating documentation. Tailoring content to the needs and expectations of different user groups ensures clarity and effectiveness. Beginners benefit from detailed explanations and examples, while advanced users appreciate concise technical details and references. Contributors need guidance on setting up development environments and adhering to coding standards, whereas maintainers require information on testing, debugging, and releasing code. By customizing your documentation to match the audience's level, style, and purpose, you enhance usability and foster a more supportive and productive community.

已翻译

赞
Abhishek Gupta

Leading Automation Solutions for the Logistics & Warehousing Sector | Movel AI
举报内容
Learn from Open Source Repositories: There are numerous open source repositories that have exceptional documentation. These can serve as reference points for writing your own. For instance, larger projects on GitHub often have well-maintained and detailed READMEs, FAQs, code of conduct, contribution guidelines, and wikis. Reviewing these can provide insights on how to structure your documentation, phrase explanations, and organise information. The more you explore open-source documentations, the more insights you gain on writing better documentation.

已翻译

赞

2 Use a consistent structure

A good documentation should have a clear and consistent structure that helps the reader navigate and find what they need. A common way to structure ROS documentation is to use the standard ROS wiki format, which includes sections such as Package Summary, Overview, Nodes, Services, Parameters, Topics, Launch Files, and Dependencies. You can also use other tools and formats, such as Sphinx, Doxygen, or Markdown, as long as you follow the same conventions throughout your documentation. A consistent structure makes your documentation easier to read, understand, and maintain.

添加您的观点

Lakshmi Sowjanya Chunduri

Robotics Engineer at TCS Research and Innovation Labs
举报内容
The most commonly used tool to document your code is to use doxygen. This comes in very handy to understand every input and output parameter of a function. The naming convention of the variable would act like an icing on the cake

已翻译

赞
Sudhanva S

Among the early generation of Robotics Engineers in India
举报内容
I would like to insist sticking with REPs which would reduce the amount of detours and then document them. Make use of code-as-a-doc for design documents.

已翻译

赞

3 Write clear and concise sentences

Another key aspect of good documentation is to write clear and concise sentences that convey the main idea and avoid ambiguity and confusion. You can achieve this by using simple and precise words, active voice, present tense, and short sentences. You should also avoid jargon, slang, idioms, and acronyms, unless they are well-known or defined in the documentation. You should also check your grammar, spelling, and punctuation, and use a tool such as Grammarly or Hemingway to improve your writing quality.

添加您的观点

Gowresh Rajagopal

Leading Roboticist with expertise in AMRs and Autonomous Vehicles
举报内容
One way to start with ROS documentation is by using the rosdoc wrapper to generate an automated documentation. But a major prerequisite for the rosdoc to work is that the source code be well commented and APIs be properly defined. The generated documentation can then be edited/modified to add more details. This will ensure that a proper relation exists between the comments, APIs and the documentation

已翻译

赞

4 Include code examples and screenshots

One of the best ways to illustrate how your code works and how to use it is to include code examples and screenshots in your documentation. Code examples should be relevant, complete, and executable, and follow the ROS coding standards. You should also use the

tag to format your code blocks and highlight the syntax. Screenshots should be clear, updated, and annotated, and show the expected output or behavior of your code. Code examples and screenshots can help your readers learn by doing and see the results of your code.
###### Link to other resources
Another tip to write better ROS documentation is to link to other resources that provide more information or context for your code. For example, you can link to the official ROS documentation, tutorials, or API reference for common ROS concepts, functions, or packages. You can also link to external sources, such as blogs, books, videos, or papers, that explain the theory, design, or application of your code. Linking to other resources can help your readers expand their knowledge and find answers to their questions.
###### Get feedback and update regularly
The last tip to write better ROS documentation is to get feedback and update regularly. Feedback can help you identify errors, gaps, or improvements in your documentation, and make it more useful and accurate. You can get feedback from your users, contributors, or maintainers, by asking them to review your documentation, report issues, or suggest changes. You can also use tools such as GitHub or GitLab to track and manage your documentation revisions. Updating regularly can help you keep your documentation up to date with your code changes and new features.
######Here’s what else to consider
This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?

添加您的观点

Abhaydan Kushwaha

Digital Creator || Management || Public Speaking
举报内容
# Here are some tips to help you :_ - Avoid using jargon or overly technical terms that might confuse readers. - Use a consistent formatting style throughout your documentation. - Use ROS documentation tags such as `@brief`, `@param`, `@return`, and `@note` to document your code. - Document the services and actions used in your code, including their names, types, and descriptions. -Document the launch files used in your code, including their names, descriptions, and usage. # Some Tools for Writing ROS Documentation* 1. Doxygen 2. ROSdoc 3. Sphinx

已翻译

赞

ROS

+ 关注

给文章评分

我们借助人工智能创建了此文章。您认为这篇文章怎么样？

很棒不太好

举报此文章

查看全部

How can you write better ROS documentation?

1

2

3

4

1 Know your audience

2 Use a consistent structure

3 Write clear and concise sentences

4 Include code examples and screenshots

ROS

给文章评分

感谢您的反馈

更多ROS相关文章

更多相关阅读内容