During the entire process of software development, we create different types of documentation. Properly written and maintained documentation explains the specific features of a project, informs how we can work with them, helps us to understand the project’s functionality, and allows us to reduce onboarding costs.
At Mad Devs, we create thorough documentation at every stage of the development process. But here, we would like to tell more about the following project documentation types:
- README
- Flowchart
- Coding style guides
They help us to ensure our code complies with the client’s requirements, is understandable, can be easily modified and maintained, and is of top-notch quality.
README
README is our main document of the project. We can compare it with a description of a product: all information about the product is presented in an understandable way. If there is no description, a developer might spend too much time trying to understand what project it is and how it shall be used.
A READMEdocument is not just a mere description though. It is a document created to help you to use the repository content without external assistance. When writing a README document, we:
- Inform the reader about the repository content.
- Create a resource that allows the onboarding of a new specialist faster and cheaper.
- Provide our client with an opportunity to check what the repository is for.
- Enable developers to start working on the project after a long break without any reverse-engineering procedures.
README Components
The structure of our README documents is not fixed because the project components and resources might differ. Also, we write a README document in stages. While working on a project, we are completing its README. For example, the How to Run Tests section can be written later when the code is covered in tests, and similar.
Usually, we include the following sections in a README document.
Name - the repository name. A self-explanatory name is better. For example, if you see the name AWS-ESK Base (https://github.com/maddevsio/aws-eks-base), you aren’t going to wonder what the project is about.
Description - here, we indicate the repository content, the project (if the repository is a part of a bigger project), and why the repository resources might be useful for you. If we move on with Ansible, its description tells you everything about the repository:
Technologies - here, we list and describe the technologies used in the repository, for example:
Apollo
Apollo Server 2.0
GraphQL
Prerequisites - in this section, we list and provide links to external resources, utilities, modules that are required to make the repository resources function.
Folder structure - we describe the folder structure and their content.
How to Run - it is one of the most important sections in a README document. It explains how you can work with the repository content. For example, if it is code, this section explains how to run it on your computer. Here, we mention the mode in which it can be run:
- Developer mode
- Testing mode
- Production mode.
For Docker projects, we provide launch commands.
How to run tests - every repository contains tests, and README explains how to launch them.
How to deploy on production - if the resources shall be deployed in production, we explain how to do it, describe how they interact with external services, and explain how to set up the environment and external services such as HTTP Proxy and similar.
Configuration files - here, we describe all configuration files needed for startup of the project.
Variables - in this block, we describe all variables that can have an impact on the service. Then, we move on with variables. If the variables are in an environment, we start with the environment.
Launch parameters - if there are launch parameters, we describe them, too.
Extended documentation - if there is a landing page or extended documentation, we provide links to them.
Mockups - here, we provide links to design mockups, sketches, a psd file, interface, if any.
FAQ - in this section, we give any remarks on the repository resources. For example, if the service doesn’t function in a specific mode, or if a specific setup of a resource is needed, we mention it here.
README Formatting
What about formatting? We make it simple: we apply special formatting for:
- Code
- Console commands
- Variables description.
It is worth remembering that your README doesn’t sell your work. It explains how your product works and how it can be used, what problems it solves. It shall enable developers to understand everything about your project without delving into code. Once your document complies with these requirements, we can call it successful.
Flowcharts
A flowchart is another type of document that we use. A flowchart is a graphical representation of separate steps in sequential order. We use it as a program-planning tool to visualize what is going on and to help to understand the process. A flowchart might also show some flaws and bottlenecks in the process.
Flowcharts help us to:
- More clearly communicate the system’s logic
- Make the debugging process easier
- Make the program analysis simpler
- Provide better documentation.
While they also have some drawbacks, for example, it is difficult to draw a flowchart for complex processes, flowcharts are useful when we need to visualize the process.
Programming Style Guide
We use programming style guides to ensure code uniformity. When we work on a product, the product code shall look as if it was written by one person. Even if there are many developers working on it, the code shall be uniform.
A programming style guide eliminates the need in guessing about the style or, for example, how to name a variable. You simply follow predetermined rules.
A coding style guide also allows for more streamlined code creation and code maintenance.
What do we include in a coding style guide? Whatever is related to code: indentation, vertical alignment, variable naming, comments; to eliminate any possibility of confusion, we also include such details as folder naming, asset naming, etc.
Checking hundreds or thousands of lines of code for compliance with style guides manually is difficult if not impossible. That’s why we use linters to ensure the code complies with the accepted coding style.
Linters are tools used to analyze the code for flaws, errors, stylistic errors, bugs, and suspicious constructs. Just some benefits that we get from using these tools are the following.
Linters make code look like written by one person
We like having a project code database that looks like it was written by one person. It also simplifies the code maintainability, prevents bugs, and reduces the time to market of new functionalities.
They provide the visibility of the codebase health
We use the practice of adding a step in our CI/CD pipeline to measure the code health status. As soon as your code health deteriorates, you can notice it and take measures asap.
They increase the ownership over the code quality
Senior developers know how the code shall look and function. If there are deviations, they can propose changes to improve the code quality. However, this is not the case with inexperienced developers. Not every developer knows how to detect whether the code is of high or low quality. A linter can tell automatically when the code quality drops, and the team can make the needed changes asap. It makes the entire team take responsibility for the code.
They help to control technical debt
There are many more advanced linters that help to control technical debt. They detect issues such as style guide mismatches, poorly designed code, or code flaws, and make technical debt explicit. For example, for Go, we use ktlink, Gofmt, and detekt to manage technical debt.
There are a lot of linters for different programming languages, software integrations, and configuration files. Any check that can be automated and that we need can be turned into a linter. We can also write our own linters even though it is not a common practice in our company because there are too many of them already.
All in all, linters help us to save time, money, and productivity.
Bottom Line
As you can see, documentation is not limited to reports only. We create documentation at all stages of the development process. It helps us to write code consistently, ensure code quality, and make the entire process more understandable.
