When writing software documentation, there are many types that can be written at different levels of granularity, and they vary greatly. One of the most important aspects that an engineer should keep in mind is the target audience. As developers, our primary goal is to contribute to the bottom line of the business with software as well as its accompanying documentation. The following are examples of different target audiences, as well as what provides them the most value. It is important to note that documentation is layered in granularity, and different “layers” will provide value for different audiences. We will explore these from most broad to the most granular.
1. Upper-level management: Here, we are talking about members with broad decision-making power who benefit most from a high-level idea of a large number of systems as well as a general idea of how they work together. For executives, VPs, and similar roles, they will almost certainly benefit from simpler diagrams outlining how ALL systems work together. The value we provide is giving them a quick, broad mental model of the systems in play, which allows them to engage with one another as well as middle management in a broadly informed way. People in these roles are often very busy so its best to shoot for ~5 minute reads for them, unless otherwise asked. Popular choices for these roles include Enterprise Architecture Diagrams and technology roadmaps.
2. Middle Management: These roles will also benefit from broader, more visual overviews of the different systems that can be understood quickly. The primary difference is that documentation for them should be more detailed than upper-level management and more tailored to a particular manager’s domain within the company. We deliver value to these roles by giving them a clear, visual understanding of the systems in their domain, with enough detail for them to engage as stakeholders with developers and project owners. Docs for them should be ~15 minute reads. Good choices for these roles include things like CRM ecosystem diagrams and visual guides for how specific systems interface with one another at a high level.
3. Project owners & scrum masters: At this point, we are starting to get more granular. Roles that manage specific projects will benefit most from detailed visual diagrams that pertain primarily to the systems within the scope of their projects, as well as more broad overviews of systems that interface directly with those in their domain. At this point, we may want some documents that are not just recording how systems interact, but also walkthroughs of business workflows and logic. To properly equip project management roles, developers need to give them detailed enough information that they can knowledgeably interface with both business stakeholders as well as other project management roles and developers as a subject matter expert on the business workings of systems in their domain. These include documents such as step-by-step business process flow diagrams, step-by-step SSO logic diagrams, and anything specific to their domain and should be about ~30 minute reads or less.
4. Senior Devs / Architects: These roles benefit most from detailed overviews of how individual systems work, as well as architectural diagrams of inner workings such as ERDs and architectural standards. Quite often, these roles are actually producing this kind of documentation for other developers; it is part of gathering requirements for their projects. Whether you are the architect diagramming a system or a dev creating this documentation for architectural review, it should contain pertinent information like file structure, design paradigms, and third-party dependencies. At this point there isn’t really a time limit to shoot for, whatever is needed to fully catalog the system is what should be recorded. Good examples for these include ERDs and microservice communication pattern guides.
5. Developers: These roles benefit most from pretty much every level of granularity that we have talked about so far, as well as some additional add-ons such as READMEs containing specific instructions for installation or implementation of a system or API docs that contain all the endpoints for a service, as well as what is sent and what is returned. Devs also benefit from documentation within the code, meaning comments. Comments are a necessity in development, and most developers have at least one horror story that will be triggered with an eye twitch at the mention of “Self-documenting code.” i.e., code with no comments. An important note about comments is that they should not be pointing out what something does, but why it does it. Again, there is no real time limit to shoot for with these because they will be system dependent. The best examples of these have already been mentioned: API docs, READMEs, and comments.
In closing, before starting to write documentation, always keep in mind these four key questions: “Who will be reading this in 6 months?”, “What decision or task does this provide decision-making clarity on?”, “How technical is my audience?”, and “how long should this be?”. It is very important that both the depth of information and the format align with these questions. Keep these in mind, and you’ll be able to make sure that the right folks receive the right documentation to provide real value for their roles. Ultimately, developers are here to deliver value not just through code but through documentation that works for every role in the business.
