How to Write Software Documentation - 10 Do's and Don'ts

Build time into the schedule

Software documentation takes time – probably more time than most managers realize. If you intend to have thorough, useful documentation, you need to build time into the development schedule right from the start. This not only helps to literally reserve your developers’ time to write documentation but also helps to change the culture. Putting it into the schedule validates it as a critical piece of development, rather than an afterthought.

Keep in mind that both the client and the software development team need to recognize and prepare for this significant time investment that software documentation requires. Everyone needs to be bought in on the value it provides.

To ensure documentation is not neglected, it's crucial to:

• Acknowledge the time commitment required: When having discussions with the project team, it’s important to simply acknowledge the importance of software documentation and the time commitment that’s required to ensure it is written properly.
• Integrate documentation into the development process: Treat the documentation process as an integral part of the software development process, not an afterthought. Plan for it right from the start.
• Assign dedicated resources: Designate specific team members or roles for handling the documentation. This way, writing documentation will not be a task that competes for attention but an inherent part of the team's responsibilities.
• Schedule regular updates: Developer documentation is not a one-time task. Schedule regular time slots for updating the documentation to reflect changes or additions to the software.

Define your audience

Understanding the audience for your software documentation is critical when creating documentation. The content, language, and format of the documentation should be tailored to meet the needs of the intended users. This means walking in the shoes of the person reading the documentation and empathizing with their perspective. Some potential readers include:

• UX & UI designers need documentation detailing product features, user interface specifics, and insights into customer preferences and needs.
• Software developers require technical documentation, including code commentary, API details, architecture, and database schemas to modify and troubleshoot the software.
• Project managers or team leaders seek higher-level documentation, such as project timelines, resource allocations, feature lists, and risk assessments, to guide and coordinate teams.
• Client management teams need a blend of technical and business-focused documentation, emphasizing software benefits, functionality, and alignment with business goals.
• Quality assurance engineers need functional details, testing protocols, and specific test cases to ensure software meets quality standards.
• System administrators require documentation on system requirements, installation, integrations, security, and troubleshooting for efficient system management.
• End users value clear, non-technical guides with step-by-step instructions, visual aids, and troubleshooting tips for effective software use.

Organize in a tree structure

Organizing your documentation in a tree-like structure is an effective strategy to ensure clarity and ease of navigation. Like a tree, your documentation should start from a single root - the core concept or the main topic - and branch out into multiple sub-categories or sub-topics.

The hierarchical nature of this knowledge management system not only ensures improved navigation, allowing readers to locate information quickly but also offers scalability and ease of maintenance. As your software evolves, new branches can be added without disrupting the overall structure.

Let’s look at an example of what this tree structure might look like:

Expand as you receive questions

As the software development process unfolds, team members will inevitably encounter areas of ambiguity, undocumented elements, or challenges that require decisions before moving forward with development. Addressing these issues through a refinement and expansion of software documentation can be highly beneficial for team alignment and knowledge sharing. Consider the following approach:

• Document the query: When a team member identifies an area needing clarification or encounters an undocumented element that requires a decision, note it down. Thoroughly understand the issue's context within the software development process.
• Formulate a detailed response: Once the question or issue is clearly defined, formulate a comprehensive response. This could involve making a decision about an undocumented element, providing clarification, or even instigating a deeper team discussion. This response may include examples, diagrams, or code snippets to provide a clear understanding.
• Update the documentation: Identify where this newly resolved information fits within your existing documentation - this could be within the technical specifications, architectural overview, or in a decision log. Keep your documentation up to date to incorporate the question along with its resolution into the documentation, ensuring it's readily accessible for future reference.
• Distribute the updated documentation: Share the updated documentation, or a link to the updated section, with the individual who asked the question and the entire team. This allows everyone to refer to it when faced with similar questions or challenges, promoting consistency across the development process.

Work closely with the client

Maintaining a close relationship with the client is a crucial aspect of creating effective software documentation. The client can provide a wealth of information and insights that can greatly influence the quality and relevance of the documentation.

Here's a suggested approach to collaborate effectively:

• Review existing documentation: At the beginning of the project, you should assess any existing documentation the client has. This could be previous versions of documentation, requirements documents, SOWs, or any preliminary notes they've made. Understanding what already exists can save time, and provide a foundation to build upon.
• Get aligned early: Use the documentation as a tool to align with the client early on. In the initial stages of the project, use the documentation to guide client discussions. This early alignment can help prevent misunderstandings and ensure that the end product meets the client's expectations.
• Co-create documentation: Involve the client in creating and updating the documentation. Regularly share drafts and updates, and incorporate their feedback. This ensures the documentation stays relevant and useful for the end-users.

Don’t rely on just one person

When creating software documentation, it's a common misstep to rely solely on one person, often the project lead or a designated documentarian to handle all of the software documentation work. While it may seem efficient initially, this practice carries several risks:

• Knowledge bottleneck: Relying on one person can lead to a knowledge bottleneck. If that individual is unavailable, the project may stall, and others might struggle to fill in the gaps without access to the necessary information.
• Single point of failure: If all documentation responsibilities lie with one person, there's a risk of creating a single point of failure. If they leave the project or the company, they may take vital knowledge and context with them.
• Limited perspective: One person's perspective can limit the scope and utility of the documentation. Different team members can contribute varied insights and approaches, enhancing the documentation's overall value.

So, instead of relying on one person, aim to make documentation a shared responsibility. Encourage all team members to contribute to and maintain the documentation. Utilizing collaborative software documentation tools can facilitate this process, ensuring that everyone has access to up-to-date information and can contribute their knowledge and expertise. This not only decentralizes the knowledge but also enhances team cooperation and the overall quality of the documentation.

Don’t have more than one source of truth

In the context of software documentation, having a "single source of truth" (SSOT) means maintaining one definitive, accurate, and comprehensive set of information that everyone refers to. This ensures consistency, reduces confusion, and enhances efficiency in communication and understanding. Many teams unintentionally will have several documents that serve as a source of truth.

For example, maybe the project manager maintains a list of requirements in a tool like Jira while the client is making changes to separate a requirements document in Excel. This can lead to a whole lot of confusion and disorganization.

Instead you should be very intentional about what your SSOT is, how each team member can access it, and what the process is for making changes. Here are a few tips to implement these policies:

• Centralize your documentation: Store all your documentation in a single, easily accessible location, such as a document management system or a wiki. This central repository serves as the definitive place for all project-related information.
• Maintain consistency: Make sure all information in the documentation is consistent right from the get-go. If something changes in the software, it should be immediately reflected in the documentation.
• Control access: Implement access controls to ensure that only authorized personnel can make changes to the documentation. This prevents unauthorized alterations and helps maintain the integrity of the information.
• Utilize linking: Where possible, link directly to relevant sections of the documentation instead of duplicating information. This prevents discrepancies and keeps all information aligned.

Don’t do everything manually

Manual processes in documentation creation can be time-consuming, error-prone, and inefficient. Here are some strategies to leverage automation and tools for more efficient and accurate documentation:

There are many tools available that can generate software documentation directly from your code:

• Redocly: Redocly is a tool that lets you create API documentation from OAS files. We like that it also offers a cloud service that hosts and updates your documentation automatically.
• Confluence: A platform that lets you create and share documentation with your team. Try using macros to add dynamic content to your pages, such as charts, diagrams, calendars, polls, and more.
• Notion: Not purely a software documentation tool, but Notion has gained popularity for its flexibility, database organization, and intuitive interface.
• Document360: You can use Document360 to document your code, APIs, products, and more. We like that it has a “smart editor” that provides syntax highlighting, auto-complete, auto-formatting, and live preview.
• GitHub Wiki: Not so much a tool but a feature of GitHub itself. Try using Gollum, a git-based Wiki to level-up your GitHub-based documentation.

Don’t underestimate the value of visuals

Visual elements can significantly enhance the understanding and usability of software documentation. They can communicate complex ideas succinctly and engage the readers effectively. Here are a few ways you could incorporate visuals into your documentation:

• Flowcharts: These diagrams illustrate processes or workflows within the software, such as algorithms or user journey flows. They're crucial for outlining the sequence of operations or decisions.
• Architecture diagrams: These provide a high-level overview of the software's structure. They depict how different software components interact and can truly be invaluable for understanding system design and data flow.
• UML diagrams: The Unified Modeling Language provides standardized diagrams for visualizing software systems. Among them, class diagrams and sequence diagrams are frequently used in documentation to depict system interactions and structures.
• Entity-relationship diagrams (ERD): Particularly useful for database documentation, ERDs visually represent the relationships and structures of database tables or entities.

Don’t neglect to maintain it

Software documentation, like the software it describes, is a living entity. As software evolves and changes over time, the documentation must be updated to reflect these changes. Preventing the neglect of software documentation maintenance requires a proactive and systematic approach.

Here are some tactical techniques to ensure your documentation stays up-to-date and relevant:

• Integrate documentation into your workflow: Make documentation updates an integral part of your software development process. Just as you would not ship code without testing it, do not consider a feature complete until its documentation has been updated.
• Schedule regular reviews: Establish a regular schedule for reviewing and updating the documentation. This could be monthly, quarterly, or any interval that suits your project's pace.
• Assign responsibility: Assign specific team members the responsibility of maintaining the documentation. This helps ensure that someone is always looking out for the documentation's accuracy and relevance.