Документация к проекту на Github c AsciiDoctor и Travis CI
В данной заметке хочу поговорить о создании качественной документации к проектам. Почему это важно? Однажды я услышал одну очень правильную мысль: хорошая документация позволяет экономить деньги проекта. Каким образом? Давайте разберемся!
-
Когда к вам на проект приходит новый человек, вы можете ему дать документацию, с помощью которой он сможет ознакомиться с вашим проектом. Обычно как бывает: приходит новый человек и к нему приставляют какого-то опытного коллегу. А теперь представьте что рейт этого человека 30 $/час. В тот момент, когда он что-то объясняет и вводит нового человека в курс дела, он полезной работы не делает, ну кроме как помогает потенциально будущему коллеге разобраться с тем барахлом, которое уже понаписано.
-
Всем уже работающим на проекте это помогает быстро решать проблемы. Ну вот, скажем, когда я пришел 2 года назад на проект, я все настроил и работал себе - документация мне не нужна. Но тут вдруг у меня накрылась рабочая станция. Что делать? Всего в голове не удержать, как и с какими настройками Postgres ставить.
-
Все проекты когда-либо заканчиваются. И в момент передачи знаний документация, а точнее ее отсутствие, начинает играть очень важную роль.
Да, обычно на проектах есть какая-то документация, она лежит в гуглдоках или каких-то абстрактных хранилищах. Вроде как все счастливы. Но основная проблема - это держать эту самую документацию в актуальном состоянии. Мне, к примеру, бывает сложно всегда помнить, в каком места и как у нас называется какой-то конкретный документ. Соответственно пойти и проапдейтить его я забываю. Знакомая ситуация, не правда ли?
Как же мы можем это поправить? Хранить документацию вместе с проектом! Да, именно так. Мы же каждый день работаем с нашими проектами, качаем сорс из гитхаба, пушим наши изменения. Почему бы не делать тоже самое с документацией к проекту?
Благо, для этого уже придумано огромное количество средств и инструментов.
Самое простое, что вы можете сделать, - это написать README.md к вашему проекту на Github. Опишите там Getting Started и это уже будет огромным шагом к прогрессу.
Но иногда хочется, чтобы документация была еще и красивой, со всякими там рюшечками! Это можно сделать, если последовать этому замечательному туториалу. Там все подробно описано, за исключением пары моментов, из-за которых у меня не работало с первого раза:
|
Tip
|
Когда будете связывать свой проект и Travis CI, то параметр GH_REF нужно указывать без http(s):// в формате github.com/SergeyPirogov/VideoRecorder. |
Если вы все правильно сделаете, у вас после билда на тревисе в бранче gh-pages будет два файлика index.html и .pdf. Затем сразу же можно будет в браузере открыть эту документацию как простую веб-страницу: пример с рекордером.
Почему это круто?
-
Все знают, где лежит дока.
-
Ссылку на нее можно расшарить любому.
-
Документацию легче поддерживать в актуальном состоянии, так как ее можно править из Github или же в вашей любимой Idea. Да что там, достаточно даже простого редактора по типу Vim.
-
Вы можете легко отслеживать, кто и как изменял файл, так как вся история хранится в гите.
-
Изменения автоматически будут пересобраны на Travis CI и документация на вашем условном сайте обновится практически моментально.
Лично мне этот подход очень понравился. Теперь я стараюсь применять его для всех своих проектов. Хорошей вам документации и до встреч…