How to Write Technical Documentation for Your Next Software Project

There are many types of documentation in the software world. Of these types, technical documentation is one of the most frequently neglected. The fast-paced nature of the industry leads to the conception that time spent documenting is time lost developing and delivering features. Over time, a development team’s documentation debt (a type of technical debt) can build to a point where the idea of tackling it becomes daunting. As a project scales and teams experience churn, information can become siloed or even lost. This can then impact the efficiency of the team.

On the flipside, well-documented projects are more likely to run smoothly, especially at scale. Common tasks and important concepts explained by the docs don’t require one-on-one conversations for knowledge transfer, making things like onboarding and process management easier. Projects become resilient to unexpected turnover since documentation lets knowledge reside within a project, not within the individuals currently working on it. If a team member leaves, typically their knowledge goes with them, but this isn’t the case when things are properly documented. Well-documented projects are also more attractive from an acquisition perspective, and the documentation can assist in the associated due-diligence process.

The core misconception is that writing technical documentation is difficult or time-consuming. When done correctly, it’s straightforward to write and returns multiples on effort in terms of time saved. 

What we’ll cover

1. The essential items to include when documenting a software project
2. Advanced topics to consider for more complex and mature projects
3. What tools to use when writing technical documentation
4. How to include technical documentation in your business process to ensure it gets done

Bare Minimum

There are several “must-haves” of documentation for every software project. For smaller projects, they may be all that’s needed in terms of documentation; for larger and more complex projects, they’re the bare minimum starting point. If you’re missing any of the following, it may be difficult to operate in a day-to-day fashion, when bringing on new staff, and especially if there is unexpected turnover within the team. Make sure your bases are covered by documenting the following topics:

1. Source Control: Where the source code is located and how to access it, be it GitHub, GitLab, BitBucket, or elsewhere.
2. Hosting: Where the application is hosted and the account credentials. This should also include things like backups plus where the associated domains and SSL certificates are registered (if separate from the primary hosting account) and when they need to be renewed.
3. Deployment: Document the process to deploy a new release of your product. Cover how much of this is automated vs. manual, what steps and triggers are involved, how to debug a failed deployment, and how to roll back changes should the need arise.
4. Development Environment Setup: How to get a local copy of the application up and running on a developer’s computer. What needs to be installed, where to find things, and how to build, test, and access the app locally. Going through this process is a day-one task for new developers so having it documented will help save time whenever you grow your team.
5. Important Services and Credentials: For SaaS services like project management software, email services (such as MailChimp), analytics, etc. Make sure you’re cataloging these tools and how to access them.

When it comes to documenting accounts and passwords, I recommend using something like a Google Sheet with the following headings:

• Service Name
• Login URL
• Username (if applicable)
• Email
• Cost
• Notes

Make a habit of adding accounts to this sheet as they’re created. Having the cost listed (be it per user, monthly, or estimates based on usage) can also be helpful for calculating things like burn rate. For security reasons, passwords should be managed separately using a password manager; you may end up with some information duplicated between the two, but I believe maintaining both has value.

Good to Have

Documenting these topics isn’t essential, but they add a lot of value, especially for larger and more complex projects. They can speed up day-to-day development operations, and cover some of the trickier policy and process aspects related to things like data handling. Consider covering the following:

1. Coding Style Guide: Document your standards for naming conventions, file structure and code organization, linter settings, and general style rules pertaining to things like braces and indentation. Taking the time to formalize this adds a lot of value and leads to developers producing clean and consistent code, which speeds up the code review process, resulting in fewer bounced-back tasks. Basing your guide off of and referencing an existing standard like PHP’s PSR can make this type of documentation quick and painless to produce.
2. Development Workflow: Cover topics like what project management methodology is in use (SCRUM, Kanban, etc.), how it’s being implemented, and the meeting schedule. What is the process for task assignment through to acceptance and deployment, and what steps need to be done at each phase along the way. Also, cover the DevOps side of things, and to what level Continuous Integration / Delivery / Deployment is being leveraged.
3. Data Flow and Regulatory Compliance: Depending on your space, location, and nature of your project, you may be subject to regulations like COPA, GDPR, HIPAA, or others. If so, it makes sense to document how you’re abiding by these standards and what internal rules and processes you have in place to ensure you’re doing so. In addition, it can be wise to document your general rules for the handling of data and sensitive information in your application, and what steps should be taken to keep that information secure in both development and production environments.

Above and Beyond

If you’ve documented everything we’ve discussed so far, you’re in good shape. Still, there’s room for improvement and added efficiencies through additional documentation. Mature and enterprise-level projects may want to cover the following topics, as they help to demystify complex logic and address business risk:

1. Supporting Diagrams: Creating visual documentation like ER Diagrams and flow charts to help clarify how your application works at a core level and how its different models relate to each other. This can be especially useful in complex applications while also helping bring new developers up to speed quickly. 
2. Business Logic: If there are specific algorithms, files, or concepts that are hard to understand even with inline code comments, consider creating supplementary documentation for them.
3. Security Primer: Cover core concepts like SQL Injection, XSS, CSRF, and other common threats relevant to your project. Cite the OWASP Top Ten and tie in any information relating to mitigations and security processes that you may have in place. Also include how you’re handling access control for infrastructure such as the use of whitelisting and things like SSH and cloud hosting keys.
4. Disaster Recovery Plan: Document how to handle service outages, hardware failures, data loss and corruption, security breaches, ransomware attacks, and any other potential scenarios you can think up. If you have a plan ready, it will be easier to respond should one of these events occur.
5. Additional Topics: If you’re having repeat conversations about how to do a certain development task, how a system or process works, or you’re unable to perform a certain business function because someone is absent, that’s a sign that you should write documentation about it.

Tools

What you’re using to write technical documentation is secondary to ensuring that you’re actually doing it. Still, there are many options out there, from simple to complex:

1. README.md: the standard go-to for information related to any git-based project. This can be a good starting point for basic developer documentation. If it becomes too large, you can break it out into several smaller markdown files.
2. GitHub Wikis: for more in-depth developer documentation. Read more about them here.
3. Shared Office Suite: Either G Suite, or Office 365. Make use of the sharing functionality to build more robust documentation for either the developer or the operations side of your project. It may be helpful to have a primary index document that serves as a jumping-off point by linking to each related topic document.
4. Technology-specific documentation tools: such as Autodocs to generate documentation from code or API documentation tools like Swagger.
5. Enterprise tools: for large organizations, something like Atlassian’s Confluence may be useful, especially if you have diverse content or a need for advanced permission controls and collaboration functionality.

Start with something that meets your needs and refine your process as you go. Break files out once they start getting too long or cover too many topics, and go from there.

Getting it Done

The best way to make sure documentation isn’t neglected is to make it part of your workflow. Track new accounts as they’re created, and add to the developer documentation as your system evolves. Part of the acceptance process for tasks should be asking two key questions:

1. Does this change warrant updating the documentation?
2. If so, has the documentation been updated?

Based on the answers, it may be necessary to update the docs before accepting the task. Enforcing this requirement stops the “I’ll do it later” mentality that leads to things sliding, as developers often want to complete tasks and then quickly move on to the next one. You may also want to have the documentation quickly peer-reviewed (like a code review) by another person to make sure it’s clear and covers the bases before it’s accepted. 

If you haven’t been doing this and you’re looking to improve the documentation for an existing project, don’t get intimidated. Address one topic at a time based on importance, and work through things until you’re caught up. From there, make writing docs part of your daily workflow as discussed above.

Summary

Effective technical documentation is a valuable resource for projects. By centralizing information and defining processes, teams are able to be efficient in both their day-to-day operations and periodic tasks such as onboarding new developers. Failing to keep documentation up-to-date is a disservice to a project, and will lead to problems as it begins to scale.

There are a handful of essential topics to cover when writing docs. For clients/product owners, it’s primary accounts and policies critical to the business. On the development side, it’s the process to get up and running, code style, and task workflow through to deployment. All this can be done without much effort by using freely available tools, and building it into your business process ensures that it gets done.

Every time you’re able to direct someone to the docs to answer a question or explain how to do something, that’s time saved. Going forward, aspire to make your documentation more robust by looking for opportunities where additional coverage would be helpful. Engage with your team throughout the process, get their input, and make documentation a part of your culture. From there, the path will be clear for you to build great things.

Are you looking for help with your next software project? You’ve come to the right place, every Scalable Path developer has been carefully handpicked by our technical recruitment team. Contact us and we’ll have your team up and running in no time.