Имя файла readme содержит простую инструкцию, и не зря. Файл readme — это, как правило, первый файл, на который смотрит разработчик перед началом проекта. Также важно, чтобы разработчики знали, как написать хороший файл readme, который в сжатой форме передает всю необходимую информацию.
Что такое файлы readme и зачем они нужны?
Файл readme — часто создаваемый как readme.txt или readme.md — обычно содержит важную информацию о соответствующей системе, проекте или программном обеспечении. Чтобы пользователи могли сразу найти этот файл, в идеале он должен быть размещен на верхнем уровне каталога.
README часто пишется заглавными буквами. Системы, различающие верхний и нижний регистр, помещают этот файл в список перед всеми другими файлами, начинающимися со строчных букв.
Этот файл также выполняет разные цели для разных пользователей:
- Для конечных пользователей файл readme отвечает на вопросы об установке, обновлении или использовании программного обеспечения.
- Для вашей собственной разработки файл readme дает два преимущества. С одной стороны, файл readme, написанный до начала разработки, является руководством по реализации проекта. С другой стороны, он позволяет быстро возобновить работу, если проект был отложен на длительное время.
- Для других разработчиков файл readme разъясняет кодекс и предоставляет ключевую информацию для дальнейшей разработки или использования системы, программного обеспечения или проекта с открытым исходным кодом.
Что должен содержать файл readme?
В зависимости от цели использования файла readme может быть уместным, в частности, следующее содержание:
- Общее описание системы или проекта
- Статус проекта важен, если проект все еще находится в разработке. Используйте файл для упоминания планируемых изменений и направления разработки или укажите дату завершения проекта.
- Требования к среде разработки для интеграции
- Руководство по установке и использованию
- Список используемых технологий и любые ссылки на дополнительную информацию, связанную с этой технологией
- Проекты с открытым исходным кодом, которые разработчики самостоятельно изменяют или расширяют, должны содержаться в разделе «желаемое сотрудничество» в файле readme.md. Как должны решаться проблемы? Как разработчики должны продвигать изменения?
- Известные ошибки и любые исправления ошибок
- Раздел FAQ со всеми ранее заданными вопросами
- Информация об авторских правах и лицензировании
Важно написать файл readme так, чтобы он всегда был ориентирован на конечного пользователя. Это позволит решить большинство вопросов, которые потенциально могут возникнуть.
Возможные форматы файлов readme
Вы можете написать и сохранить файл readme в любом формате текстового файла. Форматы могут включать readme.txt, readme.doc и readme.1st. В зависимости от платформы, на которой должно работать программное обеспечение, формат файла readme должен быть адаптирован к соответствующей системе и соответствующей текстовой программе. Это гарантирует, что текстовый процессор сможет прочитать файл.
Сегодня разработчики в основном используют формат readme.md. Но что такое файл .md? Окончание файла указывает на файл readme в формате markdown. Markdown преобразует текст в HTML с помощью простых символов форматирования. Хорошо отформатированный и структурированный файл readme дает пользователям полный обзор проекта.
Readme.md: пример в формате markdown
Мы покажем вам по частям, как строится readme.md и какие возможности форматирования существуют в формате markdown. Чтобы обеспечить глобальное сотрудничество и предотвратить языковые барьеры, всегда пишите файл readme на английском языке.
Пример readme в формате markdown:
# Project name
***
Short description of the project.Вставьте горизонтальный разделитель с символом «***».
Верхняя часть файла readme должна содержать подходящее название проекта и краткое объяснение того, о чем проект. В формате markdown хэш-знак «#» указывает на начало заголовка. Количество хэш-знаков определяет тип заголовка:
# Headline H1
## Headline H2
### Headline H3
#### Headline H4
##### Headline H5
###### Headline H6Для обширной документации четкое оглавление обеспечивает полезный обзор:
## Table of Contents
1. [General Info](#general-info)
2. [Technologies](#technologies)
3. [Installation](#installation)
4. [Collaboration](#collaboration)
5. [FAQs](#faqs)В readme.md оглавление может быть структурировано с помощью упорядоченного списка. Просто вставьте соответствующий номер в начало строки, и список будет создан.
GitHub автоматически добавляет идентификаторы для заголовков в файле readme. Идентификаторы получаются из названия заголовка, а дефис «-» заменяет пробелы. Они идеально подходят для использования в качестве якорной навигации в оглавлении. Если readme.md предназначен для другой платформы, которая не присваивает ID заголовкам автоматически, якорную навигацию можно создать с помощью HTML:
## Table of Contents
<a name="general-info"></a>
### General InfoЗа оглавлением следуют отдельные блоки содержания на соответствующих пунктах:
## General Info
***
Write down general information about your project. It is a good idea to always put a project status in the readme file. This is where you can add it.
### Screenshot
Общая информация о проекте важна для создания впечатления о том, что он содержит, в дополнение к краткому объяснению. Маркдаун также позволяет вставлять в документацию графику, скриншоты или другие изображения. Просто напишите описательное слово в квадратных скобках, а затем URL-адрес изображения в круглых скобках (без пробелов между ними). Перед ним поставьте восклицательный знак, чтобы маркдаун интерпретировал его как файл изображения.
## Technologies
***
A list of technologies used within the project:
* [Technology name](https://example.com): Version 12.3
* [Technology name](https://example.com): Version 2.34
* [Library name](https://example.com): Version 1234В формате markdown можно создавать маркированные пункты в неупорядоченном списке, используя звездочку «*» в начале строки.
Ссылки могут быть вставлены в любое место в файле readme.md. Структура очень похожа на файл изображения, но без восклицательного знака в начале строки. Напишите слово, на которое нужно сослаться, в квадратных скобках, затем путь к сайту в круглых скобках (также без пробелов между ними).
Файл всегда должен находиться в одном и том же хранилище. Вы также можете использовать другие общедоступные файлы. Однако существует риск, что владелец может в какой-то момент удалить эти файлы, тем самым удалив их из вашего readme.md.
## Installation
***
A little intro about the installation.
```
$ git clone https://example.com
$ cd ../path/to/the/file
$ npm install
$ npm start
```
Note: To use the application in a special environment use ```lorem ipsum``` to start.Поскольку файл readme часто используется в контексте разработки программного обеспечения, хорошей идеей может быть включение в документ примеров исходного текста. Markdown предоставляет возможность форматирования и для этого. Код может быть отформатирован с помощью ««» в начале и в конце. Вы также можете использовать секции кода непосредственно в тексте.
## Collaboration
***
Provide instructions on how to collaborate with your project.
> Maybe you want to write a quote in this part.
> Should it encompass several lines?
> This is how you do it.Знак «>» в начале строки превратит текст в кавычки.
## FAQs
***
A list of frequently asked questions
1. **This is a question in bold**
Answer to the first question with _italic words_.
2. __Second question in bold__
To answer this question, we use an unordered list:
* First point
* Second Point
* Third point
3. **Third question in bold**
Answer to the third question with *italic words*.
4. **Fourth question in bold**
| Headline 1 in the tablehead | Headline 2 in the tablehead | Headline 3 in the tablehead |
|:--------------|:-------------:|--------------:|
| text-align left | text-align center | text-align right |В readme.md упорядоченные и неупорядоченные списки также можно использовать в комбинации. Просто продолжите нумерованный список соответствующим номером.
Для наглядности мы включили курсивное и полужирное начертание слов и отрывков. Вы можете создать курсивный текст, поместив соответствующее слово или отрывок между простой звездочкой «*» или знаком подчеркивания «_». Для создания полужирного форматирования введите удвоенные звездочки или знаки подчеркивания.
Таблицы также могут быть вставлены в readme.md с помощью формата markdown. Вы можете создавать таблицы с помощью символов «|» и дефиса «-«. Двоеточие указывает, как должен быть выровнен текст: по левому, правому или по центру.
Шаблон примера Readme
Ниже вы найдете краткое изложение примеров из статьи в виде шаблона readme:
## Table of Contents
1. [General Info](#general-info)
2. [Technologies](#technologies)
3. [Installation](#installation)
4. [Collaboration](#collaboration)
5. [FAQs](#faqs)
### General Info
***
Write down general information about your project. It is a good idea to always put a project status in the readme file. This is where you can add it.
### Screenshot
## Technologies
***
A list of technologies used within the project:
* [Technology name](https://example.com): Version 12.3
* [Technology name](https://example.com): Version 2.34
* [Library name](https://example.com): Version 1234
## Installation
***
A little intro about the installation.
```
$ git clone https://example.com
$ cd ../path/to/the/file
$ npm install
$ npm start
```
Side information: To use the application in a special environment use ```lorem ipsum``` to start
## Collaboration
***
Give instructions on how to collaborate with your project.
> Maybe you want to write a quote in this part.
> Should it encompass several lines?
> This is how you do it.
## FAQs
***
A list of frequently asked questions
1. **This is a question in bold**
Answer to the first question with _italic words_.
2. __Second question in bold__
To answer this question, we use an unordered list:
* First point
* Second Point
* Third point
3. **Third question in bold**
Answer to the third question with *italic words*.
4. **Fourth question in bold**
| Headline 1 in the tablehead | Headline 2 in the tablehead | Headline 3 in the tablehead |
|:--------------|:-------------:|--------------:|
| text-align left | text-align center | text-align right |Используйте WYSIWYG-редактор от Dillinger, чтобы быстро и легко создать readme.md.