When starting a software development project, one of the most important considerations to make is how you will document the details of the software you are building. You may not realise it at the time but think about this scenario. You engage a software company. At first it goes well. But you soon realise they lack the expertise or the processes to deliver your project the way they initially promised. It’s something we’ve seen happen again and again. A new enquiry comes through after a bad experience and we try to save the project. But instead of looking through a well documented application, we must decipher the source code to understand the original developers intentions (which can be difficult at the best of times).

Why is software documentation so important?

When starting a new software project, it is critical to the long term success to ensure you are diligently documenting as much information as possible throughout the process. Think of this information as the manual to your software that should enable another person to pick up where others have left off and continue working.

The primary purpose behind documentation is ensuring continuity. See our example above for reference. You do not want your new developers to have to dedicate a significant amount of time reverse engineering the decisions made when initially developing the software so they can understand how the system works. This time and money has to be dedicated to just understanding what and why the software functions in the way it does, all due to poor documentation of the product when it was being built. This will delay the time before the new developers can even start working on the product to extend its capabilities.

If the documentation were a focus both before and during development, the burden on the new developers could be reduced. They would be able to study the existing documentation to get up to speed on how they system functioned, rather than reverse engineering it, reducing the time before they can continue developing the platform. This same scenario is applicable even if you have internal developers. In an agile software project it's so critical to keep momentum up. This is lost when trying to decipher your software.

What should you document?

When beginning a software project, there are three types of communication that occur to make up the artefacts required for a software development project: language, text and pictures. It is important to document as much of this initial discovery process as possible, be that by recording the meetings you have (language), writing notes and documenting why decisions are made (text), and take photos or screenshots (pictures) of any kind of mind mapping, whiteboarding or diagramming you and your team may do. Ensuring you are recording this information from the beginning of the process sets you up for success as you continue down the path of software development. The key piece of documentation to ensure is created at this point is the business case for developing the software. Having this ensures the businesses decision for creating this software is clearly articulated.

When moving into the scoping phase of a project, documentation is even more crucial. It is at this point where several very important design and technical decisions will be made, and it is important to have all of these decisions clearly articulated. At WorkingMouse, some of the artefacts we produce and document include but are not limited to:

• The entity diagram of the application (database schema),
• Backlog of requirements including both Epics and User Stories,
• Prototypes and key design decisions made,
• User interviews and feedback,
• Any major security or technical decisions made,
• Estimations spreadsheet,
• Ticket prioritisation.

The next phase in the development cycle is to start coding the software. At this point, it is pertinent to ensure your developers are diligently commenting their code and documenting any major technical decisions they make. At WorkingMouse, we bake this time into our estimations, called Iteration N, to ensure our developers have an adequate amount of time during development to document their code and clean it up. This time in Iteration N ensures the codebase and documentation is ready for other developers within WorkingMouse or our support team to pick up.

Lastly, once development of your software has finished, it will be passed on to a team to support the application. When supporting an application, the team will make many decisions about the deployment of the application and any bug fixes they make. It is pertinent all this information is included in the documentation of your software.

Where should you document your software?

As you can see, there is a lot of information that should be documented when developing a piece of software and the last trap you want to avoid falling in to is having this information stored in a number of disparate locations. Having a centralised place to store all your documentation is critical, as without knowing where all your documentation is stored, you may as well not have written it. At WorkingMouse, we use two major software packages to store our documentation depending on the needs of the client, the Atlassian suite of products and Codebots.

The Atlassian suite contains a number of products for supporting software development, project management and content management. The two key products we use are Jira and Confluence. Jira helps plan, track and manage software development projects by providing tools to track tickets, bug fixes, time spent on a project and the backlog of a project along with several other features. Confluence on the other hand is a knowledge base, where more general information on the project can be stored in a centralised repository such as project artefacts. Both Confluence and Jira connect with one another, allowing seamless information sharing between both products.

The Codebots platform also looks to centralise the documentation of a software development project in one place. Codebots is our platform engineering tool that modernises enterprise software delivery for digital transformation and legacy systems. The Codebots Library acts as the knowledge base for all artefacts, similar to Confluence, as well as documentation of any code written by the bots (and humans) known as the reference implementation. The planning section enables the team to map out the backlog of requirements and tickets they are working on as part of the project. Further, the Codebots platform also stores vital information such as the entity diagram and security matrix.

Regardless of the software package you use to document your software, what is most important is that you are diligent with recording as much information as possible and centralise the place in which you store that information. This ensures that the transition of your software project to a new team of developers or for handover to support is as painless as possible.