Challenge for the Community – Show Us the Bugs!
Network to Code is stronger from community participation. From interactions in the NTC public Slack workspace to community-initiated issues and PRs on GitHub, I can speak firsthand how this feedback is used in the effort to improve the quality of NTC’s projects, and the value they provide to the community.
This week’s Nautobot post deals with a specific situation that sometimes arises: hesitancy to open bugs on documentation.
An Error, Omission, or Unclear Instruction in Documentation Is a BUG
Good documentation is foundational to usable software: if the docs are not clear, it almost doesn’t matter how good the software is, because the bar for usability becomes very high. That’s why it is so important to understand if the docs for any of NTC’s projects are not clear or otherwise have errors or omissions.
As someone with an open-source project that leverages quite a few external packages, I can attest to how important documentation is. Well-written, clear documentation lowers the bar for effort to use the code because it:
- Helps users to implement the code better
- Helps users to understand expected behavior
- Helps users to find features
- Speeds up development time
- Prevents frustration (specifically, throwing half-empty bottles at my screen)
Impostor Syndrome
Let’s deal with this head-on: we’re all trying our best, and we all have different skill levels:
- Some of us are experienced network engineers, some are not
- Some of us have experience with code, some do not
- Some of us have experience with systems, some do not
- Some of us have experience with containers, some do not
- etc.
The point being, most of us know enough to know that we don’t know everything. If we don’t understand documentation, we can feel that we’re doing something wrong and that we don’t belong here. This can lead to impostor syndrome: everyone here is smarter than I am, and I have no business giving feedback.
But the exact opposite is true: because you don’t know everything, you should provide feedback. The next section covers why this is true.
It’s Tough to Write Good Documentation
The people writing the docs have tough job. They have a certain level of knowledge they can draw upon; however, they don’t know what they don’t know, and they don’t know what any given reader knows and doesn’t know.
This is a tough situation, made tougher by the competing interests of (1) adding more details, versus (2) the time and effort it takes to add those details.
Receiving documentation bugs from the community helps the authors understand where their blind spots are. For example:
- If the docs have too much info, they may need to be reorganized into smaller sections
- If the docs are too verbose, they may need to be reworded
- It’s often difficult for someone who created a solution to understand all the details the users of the solution will need
- We may need user guides for some topics when:
- There are a lot of users new to the solution space
- The user base has varying levels of skills in each of many skill set silos
- etc.
As someone who has written a good bit of documentation, I fully understand that writing good documentation is impossible without feedback.
Community feedback helps us understand our blind spots. Understanding these blind spots leads to better docs, which lead to more usable software and greater value for the community.
PRs Make You a Contributor!
Another valued way to contribute is to offer corrections/additions to the docs yourself in the form of a pull request (PR). There are mutual benefits to this:
- PR Author: When the PR is approved, the author officially becomes a contributor for the GitHub repository
- Community: Better docs and more usable solutions
- NTC: It gives NTC the exact user-desired end state, which saves time
Submitting a PR is a great way to start building a publicly accessible body of work while also providing value to the community.
Conclusion
As part of my role as Developer Advocate here at NTC, I attend the daily stand-ups with the Nautobot Core Team and interact regularly with a lot of the consultants and engineers who create and maintain various apps and other projects in the Nautobot ecosystem. I’ve witnessed firsthand the serious consideration given to opened bugs, PRs, and other feedback on the docs. I’ve also created a few docs PRs myself and have been encouraged throughout that process.
Community feedback allows NTC to better serve the community.
Thank you, and have a great day!
-Tim
Tags :
Contact Us to Learn More
Share details about yourself & someone from our team will reach out to you ASAP!