How To Approach The Internal Documentation Of Your Software Projects?

Many Software Architects, Developers, and Leads face this question for their projects – whether they should document their projects? If yes, how much? No, we are not talking about the required documentation that almost every software project needs, like the customer-facing documentation. By “internal documentation”, I am talking about technical documentation like Architecture and Design documents. In this post, we will discuss how to approach such internal documentation.

Why Document Your Project?

This is the most important question. Simply put, what is your intent behind documentation? Are you planning to use it as a tool that can help you build more quality software or are you simply putting together some artifacts for the sake of it? And, this is not just a question for the Architects and Designers, but also the entire team. After all, when you are investing time and effort in the documentation, most of the team should benefit from it. Projects that take the approach of using documentation as a tool to build more quality software not only benefit from it, but these have more useful documentation.

Pros of Technical Documentation

The following are some of the common benefits of having technical documentation.

• It helps validate the approach, design, and implementation.
• It can help establish the core concepts and avoid common misunderstandings.
• The same artifact can benefit multiple aspects of the software life cycle. Remember that the same document may be consumed in different ways by different team members. For example, while a developer may look at it for their implementation, a quality assurance team member can use it for writing their test cases.
• It can significantly help in ramping up new team members who join the project later.
• It establishes transparency in sharing information that could benefit the entire team.
• By keeping it up-to-date, it can help avoid redundant communication.

Cons of Technical Documentation

Of course, documentation comes at a cost. These are not necessarily cons of documentation but are associated with it.

• It requires a time investment.
• It runs the risk of getting outdated as the project progresses. This is often the case when documentation is produced for the sake of it but is not being used for anything meaningful.

So, as you can see, it all boils down to the point about the purpose of the documentation.

How To Approach Technical Documentation?

I am a big believer in using documentation as a tool to deliver quality software. Hence, I like to invest time to make it more meaningful. Here are some useful tips that I like to consider for the documentation.

• Establish the core concepts: Having a simple section like glossary is good. But, often you, as a designer, may have some core concepts that you would like the team to understand. Just like in the business world, there are key driving factors, there are certain core concepts that are key to the functioning of your application. For example, specific data model elements, algorithmic constructs that can help the team understand how the system is architected and what was the thought process behind it. It is interesting to come back to this section a year later and find whether these are still applicable!
• Organize effectively: Avoid clubbing multiple types of content in the same section. It not only makes it harder to understand, but it could create confusion and make it difficult for other team members to extract information. For example, instead of including data model, deployment, performance altogether, consider splitting these into separate sections. For more complex projects, it may be worth having dedicated documentation for certain components/services and having links to these from the overall project-level documentation. This way, team members focused on those components can find information more easily. It would also make it easier to delegate ownership of maintaining this documentation.
• Be concise: The good thing when you write is you can try to articulate your thoughts as concisely as possible. I like to use bullets over paragraphs especially when the topic is dense.
• Keep it simple: That goes without saying. Avoid the use of complex words and jargon that are not helpful. Of course, if some complex terms are vital from an understanding perspective, use these, but make sure that these have been clarified.

What Should I Include In My Software Design Document?

A Software Design Document (a.k.a. SDD) is a living commentary of your project. The following are some key pieces of information that I would like to include in an SDD.

Note: I talk about multiple diagrams as each diagram helps in analyzing the application differently, and collectively these help in gaining a more complete picture.

• Glossary: This captures the key terms that consumers of the documentation should be familiar with. For example, any important abbreviations you are using throughout the documentation.
• Architecture Overview: An overview of the System Architecture. This is a very high-level blueprint of your application, such as an n-tier architecture that will typically not change much over the life span of the application.
• Key Concepts: We talked about these earlier in this post. This section should cover the key concepts and how these work together to make your application function. Also, coming up with meaningful names for these concepts can often help you convey a specific point easily as opposed to always explain what you are talking about.
• High-Level Design: This should capture the overall system design, key components, and their dependencies. Often a UML Component Diagram can come in handy here. The idea here is to give sufficient guidance to individual components’ leads to understanding how they fit in the overall picture. At the same time, giving them at least some level of flexibility in their specific component design, as appropriate.
• Deployment Diagram: If there is one diagram you must-have in almost every SDD, then this is the one. It helps in establishing key details like deployment nodes, which components will run on these, ports exposed, protocols used, and the direction of communication. This is often accomplished via a UML Deployment Diagram.
• Data Model: This is at the heart of many enterprise applications. At a minimum, this should include key entities and their relationships. Often, this will be the input for the database implementation. Entity-relationship Diagrams or ER Diagrams are often used to capture this.
• Class Diagrams: Having one or more Class Diagrams that cover the key classes and their relationships can help the team members build a better understanding. Here, you should focus on core classes that contain business logic and avoid cluttering with classes that are only relevant from the data perspective. Those would typically have been covered in the Data Model anyway.
• Interaction Model: This helps in understanding component interaction in chronological order. This is often captured via UML Sequence Diagrams.
• Compatibility Matrix: If your application has specific compatibility requirements, such as operating system version, library versions, etc it is worth capturing these. These details are extremely important for testing as well as for customer documentation.
• Dependencies: Any third-party libraries or other dependencies that your application requires. This is important for technical aspects like builds. It is also important for legal because, at times, developers may pick up a library that may not be the best choice from a legal standpoint. So, the sooner you can jot down this list and get clearance from stakeholders, the better.
• Performance and Sizing: What are the sizing recommendations and what performance objectives and criteria do the design cater to? The answer may not be always simple and may require a few iterations. However, the point is to have at least some level of guidance and tweak it based on learnings.
• Security: Although other sections may touch upon it, it is important to make this section and address any specific security measures implemented in the application. This could be the use of secured protocols, network configurations, even some operational aspects like regular scanning and detection. This is not an operational document but should give guidance to the Operations team so that they know what measures they should have in place to secure the application.
• Enterprise Readiness: This covers various other aspects like high availability, accessibility, etc.
• Install and Upgrade: This section should cover considerations for fresh installation and upgrades. It is worth including any specific design considerations, such as the backward compatibility of the data model.
• Revision History: Finally, a section that contains the timestamp, the change author and a quick comment describing the change.

The following are some not so commonly used sections. But, I like to use these in my SDDs as this helps bring in a lot more clarity and enabling various teams (including the support teams).

• Developer Notes: This section contains useful tips and information on the code-level information. For example, how multi-threading should be used for a specific component, use of tokens to identify a request end-to-end, etc.
• Logging: Include specific patterns for details like understanding the flow, identifying a request, etc. Sample log snippets also can be extremely helpful.
• Troubleshooting: Provide information on how to troubleshoot the application. This should cover things like log locations, how to analyze logs, other system parameters to analyze, etc. If you can take a few key scenarios, that can also be helpful.
• Common Problems and Solutions: This is useful to capture the commonly observed issues and provide guidance on how to resolve them. As you can imagine, sections like these will continue to grow and can provide extremely useful information for the support knowledgebase.

There are a lot of areas to cover and not everything needs to be done on day one. However, having place holder sections and updating these over time can help you in building useful documentation.

Handling Future Updates To Documentation

Keeping documentation up-to-date is critical to ensure it continues to be an effective tool. Good checkpoints when you can ensure that the documentation is updated.

• Any important technical assumptions are introduced or changed
• Agile iteration boundaries
• When new features are developed
• When new major release begins

Conclusion

As we can see from this post, technical or internal documentation can be a quite effective tool in building quality software and keeping teams in sync. Hence, instead of looking at it as an overhead, look at it as an investment that will pay you off as you embark on your software journey.

Happy developing!
– Nitin

 

---

Also published on Medium.