Software development consists of writing tests, code, and documentation. While test-driven development (TDD) has become very popular, many development teams still struggle with creating the right amount of documentation. Writing too much documentation is wasteful, but some documentation is necessary to keep everyone on the same page. In this article, we will look at some documentation best practices to help you efficiently create high-value documentation without wasting anyone’s time. Many development teams struggle with writing the right amount of documentation — too much or too little can be harmful.

What is Documentation?

Effective documentation ensures that stakeholders, developers, and users are all on the same page. Developers may write documentation for other developers to better understand the code; product managers may write documentation for developers to better understand the requirements; or, the organization may write documentation for end users. There are several different types of documentation:

• • User Documentation is designed to help end users use the application. For example, Stripe’s legendary API documentation is designed to help businesses integrate payment processing into their web applications.

• • Support Documentation is designed to help end users complete common tasks or troubleshoot issues. For example, Quickbooks may write documentation covering how a user can generate and send an invoice.

• • Operational Documentation specifies how an application will function through user stories, acceptance criteria, design documents, and other types of specifications. These are a form of internal documentation.

• System Documentation is designed to help internal developers quickly find classes, methods, variables, and other code that they need to complete their tasks. This documentation is a lot like a quick reference guide.

The amount of documentation that’s required varies depending on the project. Small software projects may not require system documentation and internal projects may not require support documentation. It’s up to your team to decide how much is necessary and balance that against what’s required to keep that documentation up-to-date.

Documentation Best Practices

Traditional waterfall development involves writing a lot of documentation at the onset of a project. Documentation is written covering the application architecture, user interface/design, user experience, and API before a single test or line of code is written. Of course, this is risky if things change. Agile development is focused on simplicity—that is, the art of maximizing the amount of work not done. In Agile development, the focus is on writing as little documentation as possible early on. The documentation evolves as the project reaches maturity and more information is known. [content_upgrade cu_id="4881"]Bonus Content: Checklist of Software Documentation Tools[content_upgrade_button]Click Here[/content_upgrade_button][/content_upgrade] Let’s take a look at some Agile documentation best practices.

Write Understandable Code

Developers should strive to write self-explanatory code. For example, classes, methods, and variables should have human-readable names that convey their purpose. The Single Responsibility Principle and other application design principles also make the code easier to understand. Code should also be organized in a way that’s intuitive to others working on the project. For example, Ruby on Rails “convention over configuration” principles make the framework extremely easy for new developers to jump into—there’s no question where every part of the application can be found. In-code documentation can also be helpful. For example, docstrings can be very helpful for defining the purpose of a class or what parameters a method takes. Some in-code documentation is even integrated into an IDE, which can make the classes or methods easier for other developers to use. Test-driven development also minimizing the amount of code written, making the code base much easier to understand. For example, a developer might write a unit test the fails and add the minimum amount of code possible to make it pass. They aren’t thinking about any externalities that could result in more code than is necessary.

Use Executable Specifications

Many traditional specification documents, such as requirements, architecture, or design specifications, can be captured as executable specifications. Behavior-driven development formalizes this process and effectively creates up-to-date documentation as part of the development process. HipTest’s living documentation takes executable specifications and presents them in a way that’s human readable. In addition, it’s easy to see the history of a feature, when it was last updated, and other key information. [caption id="attachment_4797" align="alignnone" width="1600"] HipTest Living Documentation[/caption] Since executable specifications are the starting point, they are constantly kept up-to-date through automated testing and continuous integration. Business teams know that the living documentation is up-to-date when communicating features to clients, while developers can use it as a reference.

Treat It Like a Requirement

Documentation should be incorporated into your development process in the same way as testing—as a requirement. You should estimate it, prioritize it, and put it in your work item stack alongside everything else that you need to address in order to make sure that it actually gets done. Executable specifications should be completed at the beginning of a release cycle since it drives the rest of the development process. For example, you might write Cucumber tests at the beginning of the development cycle, write lower level tests to cover the specifics, and then write the code last. Architecture, user, and support documentation are best written at the end of the release cycle when all of the information is known. If you create these kinds of documentation too early, you may end up wasting time since parts of the documentation must be changed later. It’s important to keep all of this documentation in the same place. For example, HipTest’s living documentation aggregates all executable specifications in a single place for business or technical teams to access. Swagger, Confluence or other tools are commonly used for other types of documentation.

Automate the Process

There are many different ways to automate the documentation process. For example, Javadoc looks at structured comments in Java code and automatically generates system documentation containing descriptions, parameters, return values, and other data points that can be invaluable for other developers. [content_upgrade cu_id="4881"]Don't Forget to Download Our Free Checklist of Documentation Tools[content_upgrade_button]Click Here[/content_upgrade_button][/content_upgrade] If there are no structured comments, some system documentation generators can automatically determine classes, methods, and variables based on context. Swagger Inspector, for example, generates OpenAPI definitions during runtime and autogenerates documentation of the application API. HipTest’s living documentation also automatically generates up-to-date documentation when integrated with a continuous integration platform. Every time a BDD scenario is added and successfully run, the scenario is automatically added to the human-readable living documentation.

The Bottom Line

Documentation is an extremely important part of the software development process. In fact, many Agile development shops have started taking a documentation-first development approach. A great example of this is creating living documentation from executable specifications, which is possible using HipTest. By adhering to the best practices outlined above, you can ensure that you have the right amount of documentation for your project. [embed]https://www.youtube.com/embed/o9tg2t5WxdM[/embed]