The three types of Documentation that you must have on your code repository

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. It is easy if you have a markdown file and wish to move to Asciidoc.

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

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.

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: https://dzone.com/articles/doc-project-guide