Useful Tips

How to write a good readme and why it matters

Pin
Send
Share
Send
Send


A Readme file is a small document that is usually attached to the program. Readme files are written by software developers and contain basic information about the program, including installation information or a manual on system settings, contact information, license, acknowledgments and information about the software version. For software distribution, it is important to know how to write a Readme file. A poorly written Readme document can frustrate a user, while a successful one will help him to easily learn basic information about your program.

Who is reading README?

If you think that you are the only one who will watch your project, then this greatly reduces the desire to write a good README. But in fact, regardless of whether it is a large project or a small one, you should always be proud of the code that you wrote, because you will never know who will see your project today, in a week, a month or even years.

You can show your projects to friends or your future employer will want to check your public projects. Switching between projects is normal, so even you yourself will return to your projects from time to time. Depending on the role you are playing, you will have different goals for reading README. Let's look at some of them.

What kind of project is this?

A few weeks ago, I searched on the github for open source games that are under active development. In this situation, even a minimal README that describes what the game is doing (or what should) will be very useful. README will generally be a great help for another developer who is looking for a new idea.

Unfortunately, I found only 1 out of 10 recently updated games with a description of what this game is.

Rules for registering a README.MD file on GITHUB

If you started working on GitHub, decided to upload your project there for collaboration with like-minded people, then most likely you will first of all face the problem of creating the first file - the “readme.md” file.

You can, of course, just lay out a simple, unformatted text file. But you will want to make it readable so that links are highlighted, blocks of code, tables are present, and so on ...
This article will help you with this.

GitHub uses fairly simple rules to format text. I will list the main and sufficient, as I do not pretend to be a complete official guide.

Text can be processed in any simple text editor, for example, in Notepad ++, which I use myself. And you can directly edit the file on GitHub online.

The stylistic markup should be like this:

Pagination is done by inserting an empty line between them (press "Enter" after the paragraph).

Horizontal line between paragraphs - tag - three or more stars or hyphens

Next are the headers and more:

Link design [Visible part, link name] (http://webdesign.ru.net link address - invisible part)

If you enclose the address in angle brackets, it will automatically become a link

Bold

Highlighting directly in the text

A block of text with a darker background, four spaces (or more) from the beginning of each line

Blocks of text with bad syntax. Block with html code highlighted in background color. Tags are highlighted according to html rules.

Block with php code highlighted in background color. Tags are highlighted in color according to php rules.

Highlighted background block with cascading tables. Tags are highlighted according to css rules

The block of text, highlighted by a dark stripe on the left edge (quote)

Nested citations are allowed (quote in quote). Then the second-level quote is highlighted by two ">>" characters, and the third-level quotation by three.

Table with alternating light and dark lines (zebra)

Listing - Unordered List

A numbered list is made even easier:

italic - oblique font. Space, punctuation, or underscore cancel marker rule

By combining these markers, you can correctly mark up your text, make it more understandable.

I hope you find this article useful. Good luck on GitHub!

UPDATE!

Insert image into text

An exclamation mark denotes an image, a brief description is given in square brackets, and a full link to the image in ordinary parentheses.

Published by Administrator - March 25, 2016, 14:46 - 15350 views

How to set up a project?

I recently changed jobs and got a new, clean laptop. Despite the fact that only a few weeks have passed since my last article, I could not remember how I put together this site and how to put it together on a new machine.

The installer may be written by you, your colleague, or a developer unfamiliar to you at all, but the time you spend again figuring out how to install the project will be wasted. The best thing you can do is write a short installation guide that will help the new person get started with the project faster.

Project Options

As the project grows, more and more people will participate in it, more and more parameters that can be changed will appear. How to change global variables? How to enable debug mode? What can be changed in the config file? All these items need to be reflected in the README file so that users can access all the features.

Assembly and deployment

After the project has passed the initial stage of development and reached the stable version, usually, you need to take additional steps to deploy the project.

Look even at this blog: I can work on certain ideas for a while, and then postpone the blog for weeks. But even after working with various projects, languages ​​and CMS, I can always find out how to properly deploy each of the projects.

Creating even simple (and preferably copied) assembly and deployment instructions will ensure that you can deploy the project when the time comes.

Contributing

Each project has its own practices and standards, based on the team that develops it.

README should include a small introduction for those who want to join projects, for example:

  • What coding standard is accepted in the project?
  • How to make commits and branches?
  • How can you discuss anything with the development team?

This can help new entrants join the project faster.

There are many articles about licenses in open source projects. But the following points must be reflected in the README file:

  • Is it possible to use, modify and add a project?
  • Can I use the project code in other projects (for example, at work)?

It is better if the answers to these questions are written next to the license. This will save other users time searching for answers.

What's next?

All of these issues should be reflected in the README. Unfortunately, to reflect all of them in README, you need to spend a lot of time. In addition, this does not seem to be the most important when work is under deadline conditions.

I decided to make a template for README, which you can simply copy to all projects. Over time, the template has become an integral part of all my projects. You can find the project with the template on the github or just copy the template to your project:

Open it and, following the comments, fill it with data about your project. Most likely you will not need all the parts, so remove those that are not relevant to your project.

I will be happy to see how the template becomes even more complete. Therefore, if it seems to you that something is missing, then open the pull request to improve the template.

I hope that incorporating a good README in your projects will help you and other contributors to better support and develop the code.

Pin
Send
Share
Send
Send