Engineering Best Practices for Documentation: According to the Gun.io Community
Open Spaces is a Gun.io series dedicated to exploring the world of technology through the eyes of our community’s engineers. After writing about the 7 Reasons Documentation is Important for Engineers, I’ve asked a few developers in our Slack Cantina, a community space made up of Gun.io engineering talent, for their best practices for documentation.
Documentation Should Be Part of the Code, Not an Afterthought
“In my view, if using a feature requires excessive documentation to understand, it could indicate a design or implementation flaw. Ideally, things should be as self-explanatory as possible.”
— Ceyhun K
Great documentation begins with clean, self-explanatory code—if your code requires excessive documentation to make sense, it may indicate that it’s not as intuitive as it could be. Writing clear, simple, and modular code reduces the need for extraneous documentation, but that doesn’t mean documentation should be avoided altogether. Good documentation should aim to clarify decisions and provide insights into why certain approaches were chosen. Writing documentation should be a deliberate act with a clear purpose, focused on serving the people who will interact with your code, rather than just filling out comments or generating doc files.
“If It’s Not Documented, It’s Not Done”
“In order to keep documentation up to date, the definition of ‘done’ for a project or feature should include documentation by default.”
— Shauna G
This is big: many teams get caught up in completing features but must remember to update or write necessary documentation. The definition of “done” should always include comprehensive documentation—whether that’s comments in the code, an API specification, or external user-facing docs. When you change the code, change the documentation, too, as they need to evolve together. It’s easy to let documentation fall behind as the code evolves, but outdated documentation can be worse than no documentation at all. Make it a habit to update the documentation every time you change the code, whether you’re refactoring or adding new features—don’t forget to update docstrings, comments, or external documentation to reflect those changes.
Minimize Assumptions About the Audience
“Don’t make assumptions of the audience. Keep assumptions to a minimum, even if it seems like you’re stating the obvious, [it] makes for more thorough documentation, and makes it more inclusive for everyone at all levels of experience.”
— Shauna G
When writing documentation, it’s important to consider the experience level of your audience. What might be obvious to a senior engineer may need to be clarified to a new developer or someone unfamiliar with your code, so it’s essential to tailor your documentation accordingly. Suppose experienced engineers will use your code. In that case, you may not need to explain basic concepts, but if it’s meant for less-experienced developers or non-developers, define terms and provide additional context. Always keep in mind the background and expectations of your readers. It’s easy to assume the reader shares your level of knowledge, but your audience can include both beginners and experts. Making your documentation accessible to all levels, even if it feels redundant, will improve its utility and help ensure it’s helpful to a broader range of users.
Tips:
- Use technical language when addressing engineers, but simplify concepts for non-technical stakeholders.
- Consider creating different versions of documents for different audiences.
Don’t Assume Everything Is Obvious
“What’s obvious to you isn’t necessarily obvious to someone else. Even if you think it’s blindingly obvious, document it anyway.”
— Shauna G
“Documentation is critical because what we do is carve order out of the non-intuitive. Documenting that process reveals that wisdom to others.”
One of the biggest mistakes developers make is assuming others will understand their code as easily as they do, even if it seems simple or self-explanatory. Someone unfamiliar with the code may struggle, so it’s important to document key assumptions, decisions, and edge cases—even if they seem obvious. Thoughtful, well-organized documentation can save time and prevent confusion, especially for new team members or future you. Don’t just write for the current team; write for the next person who will inherit the code, or even for your future self. In software development, the code you write today may be maintained by someone else tomorrow, make it easy for others to understand. Whether you’re adding a new function, class, or module, imagine someone revisiting your code in six months or a year—will they understand it quickly? If not, revise and improve the documentation.
Use Active Voice and Clear Language – Don’t Over-Document
“Active voice, not passive voice. It’s usually easier to understand.”
— Shauna G
“In engineering communications, in general, certain words I call “danger words” communicate intent and emotion but not really requirements. These words include “simple,” “easy,” “just,” “any,” “all,” and “should.” When we see these words in documentation, it may be time to revise what you’re writing.”
Using active voice instead of passive voice makes sentences more direct and easier to follow. For example, instead of writing, “The function is executed when the user clicks the button,” write, “The user clicks the button to execute the function.” This simple change makes your documentation more concise and readable. Aim for simplicity by using plain language and focusing on explaining core functionality in a way accessible to technical and non-technical readers.
Tips
- Focus on high-level concepts, design decisions, and usage patterns that provide the most value.
- Break up long paragraphs and use bullet points for better readability.
Don’t Just Repeat the Code
“If your comment exactly repeats the code (but in English), it’s a sh-tty comment.”
— Malachi B
Comments should provide context and explanation—not just repeat what the code is doing. A good comment explains the “why” behind the code, not just the “what.” For example, instead of saying // increment the counter, explain why the counter needs to be incremented, such as // increment the counter to track successful transactions.
Incorporate Visuals and Provide Examples
“I can see what your code is doing because you write good code. However, I have no idea why you are doing some of the things you are doing…. Sometimes you can add a one-liner in the code, but often the context is more involved and better to represent in a separate documentation system (with illustrations).”
— Rick O
People learn better when they see code in action, and visual aids like diagrams, charts, and screenshots can significantly enhance understanding by clarifying complex concepts and providing quick reference points. Code snippets are also incredibly helpful in documentation, as they demonstrate how to use a function, API, or library, saving developers time and reducing misunderstandings. Example-based documentation shows readers how to apply the code in real-world scenarios and highlights best practices.
Tips:
- Include code snippets for technical documentation.
- Use case studies to demonstrate practical applications.
Separate Documentation for Key Processes
“I find value in separate documentation for two purposes in particular: reminder of how to do something and explaining why certain design decisions were made….Having the steps spelled out can save much headache, heartache, downtime, and frustration.”
— Rick O
“Future readers don’t have the same context as the writer, code changes over time, and there are always decisions that were made to make a piece of code less ideal than it could be.”
— Shauna G
There’s value in maintaining two types of documentation: one for the “how-to” (e.g., setting up environments, debugging steps) and one for the “why” (e.g., explaining the reasoning behind complex design choices). While comments within the code are helpful for the “how,” separate documentation—possibly with visuals—can help explain the reasoning behind difficult decisions that may not be obvious later. Code is often written to solve a problem, but the logic behind the solution isn’t always apparent from the code itself. Adding a brief explanation of why a particular design decision was made—whether related to performance, scalability, or adherence to a specific pattern—can save developers hours of debugging later. When documenting complex or tricky code, don’t just explain what it does; provide insight into why it was implemented that way.
Use a Consistent Documentation Format
“The best system is the one the team sticks to.”
— Shauna G
“Collaborating with other people who care about writing and documenting code that another developer can easily understand and work with is more important to me than any particular documentation style.”
— Jeff L
No documentation style or tool is perfect. What matters most is consistency. The most effective documentation systems are the ones that the team commits to and uses regularly, the ones everyone on the team follows the same guidelines for. Consistency in documentation style is as important as consistency in code. Stick to the same structure across your documentation to make it easier to follow and reference—sticking to the same structure across your documentation makes it easier to follow and reference. Whether it’s inline comments, docstrings, or external documentation files, a consistent format helps the reader know what to expect, with uniform heading structures, formatting conventions for code snippets, and clear, standardized naming for functions and classes.
Tips:
- Use templates to ensure uniformity across documents.
- Include a table of contents for easy navigation.
Quality Documentation Facilitates Better Collaboration
“Good documentation makes it possible for a team to run with fewer meetings and fewer urgent questions in email or Slack. It becomes essential when you collaborate across timezones or other schedules.”
— Jeff L
“Documentation is everyone’s responsibility, but there should be at least one person who manages it and herds the chickens….There needs to be at least one curator/manager for the documentation who can pester people and find places that need shored up.”
— Shauna G
Quality documentation improves collaboration by reducing the need for constant back-and-forth, especially when working across time zones or on distributed teams. Well-documented code and processes make it easier for team members to get the information they need without interrupting others, which reduces friction, boosts productivity, and ensures smoother hand-offs. Good documentation should provide value by explaining not only what the code is doing but also why it’s doing it, answering questions that new developers or even future users might have. The more context you provide, the easier it will be for others to pick up and maintain the code. While everyone on the team should contribute to documentation, having one person responsible for managing and maintaining it can ensure consistency and accuracy. Without oversight, documentation can quickly become outdated or fragmented, so a designated curator helps keep everything up-to-date.
Tips:
- Include a changelog that summarizes updates.
- Archive older versions for reference when necessary.
- Implement peer reviews for critical documents.
- Use collaborative tools (like Google Docs or Confluence) for real-time editing and feedback.
- Schedule periodic reviews and updates as part of your development cycle.
- Assign ownership of documentation sections to ensure accountability.
As the Gun.io community notes, following these best practices can help you create clear, accessible, and valuable documentation for your team. Investing time in quality documentation not only improves project outcomes but also fosters a culture of collaboration and continuous learning – personally a favorite goal of any environment.
Any tips you’d like to add? Continue the conversation on documentation best practices in our Slack thread.
