Multiplying Software Quality Using Three Documentation Types

You know that documentation is crucial in any software development, mainly because it increases the quality, decreases the number of meetings, and makes the team more scalable. The question is how to start a new repository or a non-documentation project. This project will clarify how to start documentation in a regular source code repository.

The documentation on the source repository applies as tactical documentation. There are also strategic ones that cover the architecture, such as the C4 model, tech radar, and architecture decision record (ADR), which we won't cover in this tutorial. 

Before starting, we'll use AsciiDoc instead of Markdown. AsciiDoc has several features to reduce the boilerplate and has more capabilities than Markdown. Furthermore, AsciiDoc has support for most Markdown syntax; thus, it will be smooth to use and migrate to Asciidoc.

README

The README file is onboard any Git repository. That is the first contact of a developer on the source code. This file must have a brief context, such as:

• An introductory paragraph explaining why the repository exists
• The goal of bullets
• A Getting Started section of the repository and How To Install (i.e., in a Maven repository project, you can add the Maven dependency.
• A highlight of the API

= 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.


== Samples

* https://github.com/spring-projects/spring-data-commons[Spring data commons]
* https://github.com/eclipse/jnosql[JNoSQL]
* https://github.com/xmolecules/jmolecules[jmolecules]

We have our first file and the overview of the project, what I can and cannot do, and the next step is going to the historical moment of the project and what was released on any version in our subsequent documentation.

Changelog

We can make an analogy with each version. The changelog has all the notable changes in a single file, starting with the latest version; thus, the developer knows what has changed on each version. The main goal is to be easier than Git history. Accordingly, it should have the crucial moments of each performance.

Briefly, each version has the date and the version number, plus categories of changes such as added, changed, fixed, and removed. The source code below shows a case.

= 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

Great! Now, anyone in the team can see the changes by version and what the source repository does without going to several meetings or spending time to find the proposal of this repository. Whereas those types are outside the code, let's go deep inside the code.

Code Documentation

Yes, documentation inside the code helps the maintainability of any software. It is worth mentioning as many as possible. It is mainly to destroy the idea of a self-documenting code because it is a utopia in the IT area. You can do both good code, good documentation, and a test that helps with documentation.

You can explore the source code to be complementary, explain the code design's why, and bring the business context to the code. Remember, the tests also help with documentation. 

Please, don't use the source code to explain documentation. It is a waste of documentation and a bad practice.

On Java, you can explore the Javadoc capabilities; if you are not, don't worry about which language has a specific tool for it.

Conclusion

This article explains three documentation types to start a regular source code repository. Please, be aware it is a start, and documentation may vary with the code project, such as OpenAPI with Swagger when we talk about REST API.

Documentation is crucial, and we can see several colossal software such as open-source projects like Java, Linux, Go, etc., have documentation. Indeed, with several projects, proposals, languages, and architectural styles, documentation as the first citizen is the expected behavior among them. 

I hope you understand how meaningful documentation is and good codes, and I hope that you make your and your company simpler with more documentation in the source code repository.