Thoughts on md files

2019-10-14 | 4 min reading

Why should we use md files on our projects? What are the problems they try to solve?

Let’s try to get some whys about the benefits of these files – formally README.md, CHANGELOG.md and CONTRIBUTING.md – and what are the pros and cons.

CHANGELOG.md

I got introduced to md files on open source projects.

The first file that hit my attention was CHANGELOG.md. Usually, it’s merely a set of records for the changes done.

As a developer, i think the file starts to shine during integration or bug investigation, but it can help managers and business analysts as well to gather information on a specific release.

The main questions the file tries to answer are:

when did something change?
which was the scope of the changes?
why did it change?

I found that in combination with a git subject convention and an automatic generation tool, this file gets exponentially more useful because turns to be like an index table for the codebase.

Note: Using the convention in my case was the last bit, but probably the most important. The sequence was: having a CHANGELOG.md, automatic generation and at last the subject convention.

The automatic generation tool is not mandatory, but I reckon it does save you from the tediousness of a manual procedure and thus helps to keep CHANGELOG.md in sync.

I would say that the git subject convention is quite fundamental though because allows for skim and scan CHANGELOG.md and git log.

Other additional benefits are that you speed up rollback if needed because now you know which changes are where, and versioning becomes easy to sort out because the convention helps you understand which type of changes you did introduce (in this case I mean versioning using semver).

Study Case:
One pretty interesting git convention case is the Angular commit message format.

# Convention:
<type>(<scope>): <subject>

# Samples:
docs(changelog): update changelog to beta.5
fix(release): need to depend on the latest Rxjs and zone.js

Note: It is not unusual having someone asking me about the whys of a particular behaviour and after a quick search in the CHANGELOG.md be able to promptly answer back about the related context and task number.

The convention can be tuned depending on the project type. For example, you may insert additional information such as the task number or the PR reference.

These usually get automatically converted into links on Github, Bitbucket or Gitlab.

CONTRIBUTING.md

This file is probably the most technical and is mainly reserved for the dev team. It aims to give clear guidance to newcomers and helps them on the onboard process.

For small codebases README.md can be enough but for more mature projects having CONTRIBUTING.md gives more room for technical details.

Note: In my case, README.md was exploding in size and was turning extremely technical thus the introduction of CONTRIBUTING.md.

Some of the topics you may want to touch in this file are:

an overview of the stack used and why you did pick it up
the process to set up the environment
conventions used for PR and CHANGELOG.md
description and examples of the scripts used during dev
lint script to run before making a PR
code review practices
automatic tools or plugins for the editor

One interesting first-day task probably would be to let the newcomer set up the project with only CONTRIBUTING.md as support.

In that way, if something was missing he/she would have the opportunity to improve CONTRIBUTING.md, feel ownership of the official documentation and to commit something on day 0.

Small tip:

Please, when and if you make a list of the tech stack used try to explain some whys you did have a specific piece of technology in place instead of another.

This will give some confidence to other devs if they need to update the stack.

README.md

README.md is probably the most read and popular file in your codebase because systems like GitHub, Bitbucket and Gitlab are using it as home page for your project.

Thus README.md will be exposed to a lot of non technical people as well.

Keeping that in mind, you can start writing it as a mere instruction set and then make it evolve as a quick index for all the possibles project’s stakeholders like clients, managers, designers and other teams that may interact with the project – not only your dev team.

In that sense `README.md` is the perfect place to answer questions like:

who are the main devs of this project if I need some info?
do you have a demo, if so where’s the URL?
where is the tasks board?
where are the specs?
do you have a CHANGELOG?
I’m new in the team, where should I start?

This will support the stakeholders during the project life cycle like: review, planning, meeting, support and so on.

Last note

Silly but still worth mention I believe, it is the markdown format.

I did tediously add md to all the file names because the benefits that this format introduces over txt and html.

In particular, compared to txt markdown gets automatically convert to html in all the main platforms (Github, Bitbucket and Gitlab) and at the same time, it is easier to read in a text editor or in cli than html.

For these reasons and more is quite a defacto and I would recommend it.

Last tip:

If you don’t have those files on your codebase don’t try to push too hard immediately. Simply start from creating the files, then as the need arise update them.

In this way your md files will have more organic and valuable information.