New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feedback for blogpost on READMEs #3

Merged
merged 14 commits into from Oct 16, 2017

Conversation

2 participants
@rradczewski
Copy link
Owner

rradczewski commented Oct 15, 2017

No description provided.

If someone is running into problems setting up your project, chances are they have unstaged changes, broken dependencies, or happened to pull the latest changes that contain severe bugs. This is the paragraph you need to make sure to narrow down if it's an issue with the codebase or the persons machine.

Make sure to warn them about commands like `git clean -xfd` or `git checkout -f master` though - these will remove all untracked files, even those ignored through `.gitignore`, and undo all changes they did to tracked files - possibly resulting in data loss.

This comment has been minimized.

@hollodotme

hollodotme Oct 15, 2017

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.

This comment has been minimized.

@rradczewski

rradczewski Oct 16, 2017

Owner

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

@hollodotme

This comment has been minimized.

Copy link

hollodotme commented Oct 15, 2017

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

This comment has been minimized.

Copy link

hollodotme commented Oct 15, 2017

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

This comment has been minimized.

Copy link
Owner

rradczewski commented Oct 16, 2017

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 👍

rradczewski added some commits Oct 16, 2017

@rradczewski rradczewski merged commit ae3a4af into master Oct 16, 2017

1 check passed

deploy/netlify Deploy preview ready!
Details

@rradczewski rradczewski deleted the feedback/readme branch Oct 16, 2017

@rradczewski rradczewski restored the feedback/readme branch Jan 9, 2019

@rradczewski rradczewski deleted the feedback/readme branch Jan 9, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment