Перевод статьи «Where is the best place to put your project documentation?».
Создание проекта, библиотеки или пакета это, конечно, самая сложная часть работы. Но если вы хотите, чтобы делом ваших рук пользовался кто-то еще, вам придется потратить существенное количество времени на создание документации. Это поможет людям начать пользоваться вашим продуктом. Ведь если вы не уделите времени на описание созданного вами функционала, люди просто не будут знать, как им пользоваться, а это все равно, как если бы они вообще не знали о его существовании.
Какие же есть способы изложения документации?
Readme
Начать лучше всего с файла Readme. Это обычно одна страничка с кратким изложением ключевых функций, а также описанием процесса установки и использования вашего проекта. Readme имеет большое значение. Обычно это лэндинг-страница для вашего репозитория на GitHub, так что постарайтесь кратко изложить там самое необходимое.
Readme обычно пишется в markdown-формате. Т.е., вам будет доступно базовое форматирование: заголовки, абзацы, таблицы и отрывки кода (так что добавьте примеры кода там, где в них есть необходимость).
Если ваша страница Readme становится довольно длинной, постарайтесь добавить раздел с содержанием, где пункты и подпункты будут оформлены в виде ссылок. Это позволит читателю быстро переходить к нужному разделу.
Но что делать, если страница Readme становится уж слишком длинной и вам нужно разбить ее на несколько страниц?
Wiki
Если вы ищете простое и быстрое решение, то почему бы не использовать Wiki? Большинство сервисов git-хостинга позволяют включить Wiki и начать писать страницы.
Как и Readme, Wiki обычно разрешает markdown-формат, а также ссылки между страницами. Проверьте, какой формат разметки использует ваш git-хост и как лучше всего связывать страницы друг с другом.
Начните со страницы с содержанием, где будут ссылки на другие страницы. Убедитесь, что есть простой способ возвращения на страницу с содержанием и/или перехода на следующую страницу документации.
Если вас вполне устраивает простой, но функциональный сайт с документацией, то можно на этом и остановиться. Но если вы хотите приложить «живые» примеры (CSS или JavaScript), то Wiki с этим просто не справится.
GitHub Pages
Если вы хотите создать для своего проекта более настраиваемый сайт, со встроенными примерами (только не с бэкенд-кодом), вы можете бесплатно разместить его на GitHub Pages. Есть, конечно, и другие варианты размещения, например, BitBucket pages.
GitHub pages позволяет вам или создавать собственные HTML-страницы с нуля, или воспользоваться Jekyll. В последнем случае HTML будет создаваться на основе разметки ваших файлов при отправке их на GitHub.
Если вы будете создавать собственные HTML-страницы или использовать какой-то другой сайт для их создания, вам нужно будет скомпилировать HTML на вашей локальной машине, а затем отправить скомпилированный HTML, CSS и JavaScript.
Лично я для размещения своих сайтов и проектов использую Jekyll, но мне также случалось пользоваться VuePress для компиляции markdown с использованием JavaScript. VuePress также позволяет использовать ваши собственные Vue-компоненты (полезно, если вам нужен способ их продемонстрировать).
Если вы приложили все усилия для создания продуманного сайта с документацией, вам нужно как-то дать людям знать о его существовании.
Как я уже упомянул, GitHub pages позволяет размещать только фронтенд-код, но этот сервис также дает вам возможность использовать определенные плагины Jekyll (если вы используете Jekyll). Эти плагины дают некоторые дополнительные функциональные возможности, такие как карта сайта, seo-оптимизация и RSS feed. Это может немного облегчить вашу жизнь и сделать ваш сайт более заметным для поисковиков.
Наконец, сделайте ссылку на ваш сайт с документацией в описании вашего GitHub-репозитория, а также Readme. Таким образом люди, интересующиеся вашим пакетом, смогут найти и сайт с документацией, и код на GitHub.
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]
