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.