Skip to content

Latest commit

 

History

History
59 lines (38 loc) · 2.49 KB

Writing-A-Good-Readme.md

File metadata and controls

59 lines (38 loc) · 2.49 KB

Writing A Good Readme

Doing it is simple. Usually, you generate it automatically when you create your repo. BUT the hardest part is to write it correctly. And now we all know it's a different matter.

Some links that could help:
https://www.makeareadme.com/
https://www.google.com/search?q=how+to+make+a+good+readme

Questions to ask yourself....

To write a quality readme, you have to ask yourself several questions:

Who did the project:

if you're all alone, it's you but if you've worked in a group on a project, the least you can do is to mention the friends and (because we're well-mannered) link their name/pseudo to their github.

What is it?

What is it? Is it a recipe for sauerkraut? No, it is an application intended for mobile use to find a soul mate for a English-speaking and rhubarb loving audience. Well, say it!

When did you work on it?

Was it yesterday or three years ago? Because certainly, the repo on GitHub will mention the dates but it's still more pleasant to read when a human explains to you that the website showcases the grey shrimp lovers was made during the summer of 2015 during a hackathon that took place in Miribel. Also, the mention of changes made over time may be important for some applications.

Where have you been?

Where have you been? What were you doing? During your career as a developer, you will probably have to work in several companies. It doesn't make the same sense if you explain that you worked on a billing system when you were Senior Developer at BigPrestigious Box as if you were a learner at BeCodeQuiFormeDesNewbies. Explain to us where you were in your career path when you developed your project.

What does it look like?

Because posting your code is good, but putting a little preview in the form of a screenshot (or even just your application logo) is better. And a link to an online demo is even more like a class!

The progression... Is it over?

Is it in progress? Do you want to make any changes? Do you want us to help you?

What's in it?

What's in it? Help us to understand in one sentence what we should discover in several minutes: is it in MVC, in laravel? Is it made from A to Z? Is there a database? If so, is the MCD (conceptual data model) complicated? Can you put it in the readme?

How do you install it?

It's always good to explain to friends how to set up your work locally. Either so they can use it or so they can help you improve it!

Where did it come from? A client or an exercise to do in class... Specify!