Expertise
Services
;)
Good project documentation is vital to maintaining the project integrity. It is one of the most essential aspects of keeping the project complexity at the optimal level and proper knowledge sharing.
Today we would like to share with you the types of project documentation and learn how to create high-quality documentation for your project.
We can divide documentation cases into 3 conceptually different types:
Let's find out what are the specifics of those three and how they differ from each other.
The primary purpose of the external documentation is to provide detailed information about the API that your company exposes to the public. The external documentation is an exceedingly detailed description of each and every endpoint your API provides - request type, data format, classes, method parameters, their types, expected response, status codes, etc.
The more details you include in the external documentation, the better. The reason for that is the end-user of this functionality has no access to the source code, meaning you have to answer all the questions he or she may have with the documentation you provide. If the external documentation fails to address all the issues, you should consider it incomplete.
The external documentation cannot be too flexible because a lot of independent third parties use it at the same time. With that said, constant changes to public API make it unusable.
The aim of internal documentation is to consolidate the helpful knowledge for the internal development team that modifies the actual product functionality. There is no sense in providing too specific method details because these are fairly easy to figure out from the source code. What you should concentrate on is the feature ideas and concepts tied to the product modules and features. This is usually enough information for internal developers.
The main reason why you shouldn't make it super detailed is the flexibility of the process. The under-development functionality changes too often for you to specify everything. With that in mind, focus on the conceptual details and don't dig too deep for details.
Depending on the project, the documentation writing approach may have its unique features. For instance, sometimes there is no separate internal and external project documentation, and both the internal team and third parties work with the same documentation. Alternatively, there can be internal documentation used by everyone inside and outside of the team. This may happen when some of the product features are open-source.
There are no universal rules for keeping the mixed documentation. It is always a matter of common sense and keeping the documentation readable, helpful, and most concise possible.
There is a constant problem of finding sufficient documentation to keep the project transparent. On one hand, excessive document amounts leads to complicated navigation through the documentation structure. On the other hand, too concise documentation may miss crucial information and create a distorted understanding of product modules and features in your developer's heads.
The key is to keep the minimum documentation amount that is enough to clearly understand the documented functionality. Let's figure out how to trim the fat off your project documents and keep them holistic.
There is a set of rules for keeping the documentation complexity level optimal. These include but are not limited to the following:
Let's find out how to implement these 4 techniques into your documentation.
One of the most common mistakes is repeating the same information over and over in different project documents. Here's why it is inefficient and sometimes even dangerous:
Invest your time into thinking through the structure of your documentation. For instance, if you have the Employee and Customer classes that implement the Person class and share the Age and Name properties, there is a sense in specifying these properties in the Person class documentation once, rather than in two child classes.
You need to think of the document as a unit dedicated to describing a single module of a feature. Don't try to put multiple concepts into one document. This will only make it more difficult to navigate.
For instance, don't put Billing and Reporting into a Financial document just to make one file instead of two. Firstly, this will make it non-trivial to find these modules' documents. Secondly, it will intricate the reader trying to comprehend a document as an integral piece of information.
We are talking about both text formatting and the document structure. Here's why it is crucial:
Moreover, keeping the same style highlights your brand identity. This makes your documentation visually distinctive and easy to recognize. It helps with keeping the holistic experience when working with your external documentation.
You need to keep your documentation files and folders organized, and there is a reason for that. You see, the integral approach to naming and storing your project documents greatly reduces the time needed for finding, updating, and removing existing files, as well as adding the new ones.
Here's the tip: you should implement the three-level nesting in your documentation - Project -> Domain -> Feature. This approach allows you to discover the needed project, open the domain the feature is conceptually associated with, and discover the feature document.
Keeping fewer levels may lead to storing dozens of files in a single documentation folder while introducing more than 3 nesting levels may take additional time and bring unnecessary details.
Now that we know how to organize and structure your documentation as a whole, let's dive into the contents of the actual documents in your structure. There are 3 core elements of the documentation items: visual items, text, and complementary elements. Let's discover how these impact your documentation quality.
The text description focuses on explaining entity interaction in a particular feature. You need to describe the abstraction used in this piece of functionality, as well as tell the reader how your modules, components, and services interact with each other.
Visual items are essential for a deep understanding of the underlying processes of the feature. Here's the thing: combining text and visuals greatly improves the reader experience, as they now have not only the text description but also a visual representation of what is happening in the feature. People tend to understand the visualized information better than just plain text.
A common set of standard visuals contains UML diagrams, DB Schemas, and sequences flow. You should also include your custom schemas and diagrams to demonstrate the details for a specific feature to make it easier to understand.
One more visual to consider is whiteboard sketches. Just take a photo of your whiteboard during the feature brainstorming to include it in the documentation later. It is not the best approach since the sketches sometimes miss vital information. We recommend using whiteboard shots just for additional insights into a described feature.
In addition to text and standard visuals, it is relevant to include more data to make the feature or module document 100% clear. For instance, include data templates into your documentation. This way you can show the relevant data formats and demonstrate the real-life scenario of using the feature.
Sometimes project managers and developers underestimate the importance of creating documentation before you begin building the actual product. Let's consider documentation as a project blueprint to understand the idea better. We can hardly imagine constructing a real-life building without multiple sketches and blueprints, right? The same goes for software products. These are complex structures with numerous levels of abstraction and communication. There isn't even a time chance of building a comprehensive and quality product without documenting the approach first.
Moreover, documenting your project forces you to go through your architecture multiple times and discover the majority of vulnerabilities before the development starts. This saves you a lot of time and money. Fixing bugs in the built solution is tenfold more expensive and stressful.
The quality project documentation builds a robust platform for fast and efficient knowledge sharing, simplifies the onboarding process, and saves time for exchanging trivial concepts between developers. All these aspects reduce the overall project complexity, which means a significant impact on the financial prosperity of the company.
Follow the rules of writing relevant project documentation to improve the developer experience and pave the path to the rapid and secure growth of your product.
