Skip to content
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
Merged

Feedback for blogpost on READMEs #3

merged 14 commits into from Oct 16, 2017

Conversation

@rradczewski
Copy link
Owner

@rradczewski 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
Author Owner

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

@hollodotme
Copy link

@hollodotme 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
Copy link

@hollodotme 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
Copy link
Owner Author

@rradczewski 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 2 commits Oct 16, 2017
@rradczewski rradczewski merged commit ae3a4af into master Oct 16, 2017
1 check passed
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
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

2 participants