Feedback for blogpost on READMEs

[rradczewski]

No description provided.

[hollodotme]

I have good experience with kind of a Q/A format under Troubleshooting. Because that's how it usually works when a new employee runs into troubles with the setup of a project. S/he is asking for help and (should) get appropriate answers. It also gives a more personal touch to a project when you see people interacting. So my tip would be to express issues as questions and solutions as answers. That is also a format which is easy to perpetuate over time or changing team-mates/maintainers.

[rradczewski]

Very good point, I'll add that, thanks!

[hollodotme]

Very good post @rradczewski! We're following a similar README approach in our company and created a README template in our project template, so the basic structure and nomenclature is given to new team members, when creating their first project.

In days of APIs and micro services, we also decided to add an "Interaction" section which describes how this project is related to, integrated in or communicating with other systems/projects. If it is an HTTP web-service for instance, we would describe its public API in that section like this:

API

Request

POST: /api/v1/test

Parameters

• param1: INTEGER, required
• param2: STRING, required
• param3: ARRAY, optional

Responses

Successful

{
	"result": "success",
	"message": "OK"
}

Failed

{
	"result": "error",
	"message": "Something went wrong"
}

[hollodotme]

One additional thought about keeping the README up-to-date: Make it essential to the contribution and review workflow. If a contribution makes notable changes to the project, it should find its way to the README. When doing reviews, checking the README should be on the to-do list.

[rradczewski]

Thanks for the exhaustive feedback @hollodotme! Totally missed the Q&A section, will add that and give credits 👍

As for the API documentation: I've seen library/service projects adapt a specific API.md or just generate the documentation with something like Swagger and deploy it through CI, so you can share it with consumers/users.

I'd rather leave that point out though as I aim for sharing my general recommendations for READMEs and not go too much into detail in specific project types 👍