Project Documentation: How to Guarantee Your Project Endures With High Quality

Documentation, I know, right now, you are preparing to leave this post. Documentation is not a buzzword topic, such as microservices, Kubernetes, cloud-native, etc. However, it guarantees a scalable, maintainable, and healthy project. Let's explain how to keep a better project tactically through Documentation.

Why Do We Need Documentation?

The first question around Documentation is why. Why should you spend time on Documentation instead of the code? Software development is expensive, and we must ensure this project will have a long life. To make it possible, we need to make life easier for a future engineer, who eventually might be yourself.

Therefore, good Documentation can help us:

• Make it more natural for the following developers
• Explain the reason for some decisions around the code design and, eventually, architecture.
• Avoid making the same mistake twice.
• People leave an organization, and the knowledge should not go with them.
• We don't have the power to read people's minds. Trust me; I tried multiple times.

Documentation? How About a New Technology Trend (Complexity Bias)

Very often, people come to me to ask for advice about software projects, and usually, they have these issues that happen after three years of the project:

• People need help understanding the current code in the project.
• We are still determining why the previous decisions.
• It is hard to maintain the code
• The software keeps changing
• There are components that people need to learn what they are doing, but it is hard.

Yes, those are vast bleeding matters in any organization, and we want to solve them. Still, the solution proposal goes to a different path: Rewrite a project from scratch with the newest technology language, architecture.

The sad part is it won't solve the issue; indeed, after three years, a new team in the same project will appear with the same problem.

The solution comes with the simplicity of Documentation, but why not think about it first?

It is because we have a bias around complexity! It is unconscious, but it is there; there is this article, The complexity bias: we prefer complicated to uncomplicated. It explains why we don't like the simple: we believe the smooth will fail.

We have a name for this unnecessary complexity in software engineering: overengineer. We already know it won't help, either.

There are two excellent books where it explains the complexity:

1. Just enough architecture: It mentions the power of simplicity, furthermore, a risk-driven design
2. A Philosophy of Software Design follows Leonardo Da Vinci's mind: Simplicity is the ultimate sophistication.

To ramp up, fight against our unconscious, go the simple way, and don't underestimate the power of Documentation in software.

Scalability Without Microservices?

Scalability goes beyond the possibility of increasing the number of application instances. It is the power to handle the amount of:

• People
• Culture
• Software quality
• Organization methodology
• Company goals

And Documentation might be a good ally on it.

Enemy vs. Ally

Wait! what do you mean by "might"?

As with any decision in software, there is a trade-off; therefore, no documentation implies reading people's minds, a thousand meetings, and hard scaling the whole organization.

Whereas an over-documentation is hard to maintain and becomes a fancy book nobody reads or understands.

The right balance is the formula, and so do baby steps in that direction, and it is working to roll back any decision.

Architecture vs. Design and Tactical vs. Strategy

We need an entire post to try a definition of all those terms. Primary because there is a tremendous amount of literature about those terms. 

In DDD, we have the tactical and strategic views where the tactical is closer to the code with Design and patterns such as Repository, Aggregator and entity, etc. Still, the Philosophy of software design brings a different approach where tactical is to get things done, and strategy is to oversee the code.

We won't cover the definition of those terms here; we'll cover Documentation for Design, such as giving a project repository; what are the minimum steps to archive good software?

From an architectural perspective, there is the Architecture by Advice by Andrews Law or Scalability in the architecture by Otávio Santana, where both proposed the start to good Documentation using:

• C4-model
• Tech-radar
• Clean communication or forum
• Architecture decision record (ADR)

Put In Practices

Explained the scope of this post; let's put it into practice answering the previous question: Given a project repository, what are its minimum requirements?

Using the right balance principle, we'll list three:

1. README
2. Change log
3. Code documentation

Markdown vs. Asciidoc

The first two pieces of Documentation we'll cover soon are based on a single file you can see online. It is a core principle of any documentation; it should be visible and easy to access.

If your project repository is on Github, you might be familiar with Markdown. Indeed, it is a great lightweight markup language for creating formatted text.

Furthermore, we also have the Asciidoc tools; several open sources are moving to it mainly because it is more straightforward and robust. If you have a markdown file and wish to move to Asciidoc, it is not hard to do it.

We often want a table of content on both readme and change log files. 

Where on Markdown do we need to do it manually:

# Table of Contents
1. [Example](#example)
2. [Example2](#example2)
3. [Third Example](#third-example)
4. [Fourth Example](#fourth-examplehttpwwwfourthexamplecom)

## Example
## Example2
## Third Example

While on Asciidoc, we need to fill a single line :toc: auto.

:toc: auto

## Example
## Example2
## Third Example

Markdown and Asciidoc have Github support to visualize on the browser. It is worth trying out.

Readme File

This file is the first impression of your project; this one might have considerable and transparent information about your project, mainly why someone else should take care of it.

There are several good projects READMEs:

• Spring data commons
• Microprofile config
• jmolecules

Using those as a reference, I've created my README structure template:

= Project Name
:toc: auto

== Introduction

A paragraph that explains the "why" or reason for this project exists.

== Goals

* The goals on bullets
* The second goal

== Getting Started

Your reader gets into here; they need to know how to use and install it.

== The API overview

The coolest features here

== To know more

More references such as books, articles, videos, and so on.

Change Log

A changelog is a log or record of all notable changes made to a project. It reduces your work going to a git log.

There is the whole concept here.

= Changelog
:toc: auto

All notable changes to this project will be documented in this file.

The format is based on https://keepachangelog.com/en/1.0.0/[Keep a Changelog],
and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Versioning].

== [Unreleased]

=== Added
- Create

=== Changed

- Changed

=== Removed

- Remove

=== Fixed
- Ops, fixed

== [old-version] - 2022-08-04

Code Documentation, Because Self-commented Code Is a Utopia

It is always worth mentioning that the most prominent software in the industry, which has several real cases and decades of existence, has good Documentation even in the code.

• Java (Over 25 years)
• Hibernate (over 20 years)
• Linux (over 30 years)

Those few pieces of software have endured over a decade and are still relevant in the market.

To Know More About Documentation.

This post is a brief overview of exploring good Documentation in a project. Otherwise, it would become a huge post. There are several tips to cover that need to be clarified.

As a book reference and go deeper on those topics, there is Doc for developers where the main focus is to treat Documentation as a product and readers as a user, and it explains several techniques to give a better experience for them.

Conclusion

I hope you enjoy this journey and this article about code quality using documentation. It is uncomplicated but efficient and guarantees more contribution to the code project.

Last month, in the Jakarta NoSQL, we decided to spend the whole month studying, analyzing, and applying a better documentation culture on those repositories:

• NoSQL
• JNoSQL
• JNoSQL communication driver
• JNoSQL mapping extension

You can take advantage of those to apply to your project, and yeap, once those are open source, feel free to contribute to making the documentation and the code even better. Of course, please give them a start.