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