Който чете README

Случвало ли ви се е да стигнете до страница на GitHub от търсене в Google/Yandex? Преди да се потопите в документацията, искате да разберете къде се намирате, независимо дали имате нужда от нея или не. Само за този случай те пишат README - за тези, които случайно са намерили хранилище в GitHub и искат бързо да се ориентират в мястото.

Документацията е написана във формат Markdown и е поставена в специален файл README.md до кода. Можете да научите повече за езика за маркиране Markdown в ръководствата на GitHub.

Какво трябва да има в README

Всеки проект е различен, но има няколко типични раздела от документацията:

1. Кратко описание на проекта

За тези, които се изгубят, оставят уводна дума за проекта. Просто и разбираемо обяснете каква е употребата на този код.

2. Изисквания за околната среда

Обикновено това указва типа на операционната система или минималната версия на интерпретатора на Python. За уебсайтовете е важно да знаете поддържаните версии на браузъра и формата на устройството: мобилни телефони, таблети или настолни компютри.

3. Как да инсталирате

Разделът отговаря на въпроса "Какво трябва да се направи преди стартиране на програмата?" и съдържа инструкции за внедряване на проекта. Най-удобният формат са bash командите с кратко обяснение за тях. Потребителят копира команди в конзолата и бързо ги изпълнява.

Bash кодът и командите имат специален начин на форматиране в Markdown. изглежда така:

Декорираният код хваща окото дори при повърхностен прочит, което е изключително удобно.

4. Примери за стартиране на скриптове

Ако говорим за конзолна помощна програма, тогава е полезно да покажем как изглежда резултатът от операцията на скрипта в конзолата в случай на редовна ситуация.

Ако проектът има скриптове с тестове или други инструменти за разработчици, тогава също е полезно да пишете за това,дайте примери за стартирането им.

5. Примери за използване на API за програмиране

Ако проектът се доставя като библиотека и се използва от други скриптове чрез импортиране, тогава си струва да се опишат наличните функции, класове и константи. Най-лесният начин да направите това е с примери за код, така че трябва да има много от тях.

Ако проектът е голям, тогава документацията често се поставя на отделен сайт с лесна навигация и търсене. Често използвайте услугата Read the Docs.

Модел за подражание

GitHub е пълен с проекти с добра документация. Винаги можете да надникнете нещо за себе си:

Има и готовишаблони README. Ето няколко за избор:

Изчистване на връзките

Препратките в документацията трябва да са смислени и съдържателни. Ето един лош пример:

Какво друго трябва да знаете

Друг начин е да инсталирате плъгина за Sublime TextOmniMarkupPreviewer.

Блоковете код в документацията са много важни. За по-лесно намиране те се отличават със специално форматиране.

Много е готино, когато езикът за програмиране е изрично указан иосветяването на синтаксиса работи правилно. Най-често документацията се преглежда и се разчита на общоприетия стил на дизайн. Никой няма да прочете огромно платно с лошо форматиран текст - всички са твърде мързеливи.

Документациятатрябва да бъде кратка. Трябва да пишете само за наистина важни неща, кратко и по същество. Затова по-малко думи, повече примери.

Документацията трябва да бъде написанана английски. Защото по OpenSource проекти работят хора от различни страни, а документацията на английски е стандарт.

Вземете сериозен опит в уеб разработката

Python, Git, VK API и Facebook, Django, Linux и др.Изберете с кой модул да започнете.

---