Документация к проекту на Github c AsciiDoctor и Travis CI

В данной заметке хочу поговорить о создании качественной документации к проектам. Почему это важно? Однажды я услышал одну очень правильную мысль: хорошая документация позволяет экономить деньги проекта. Каким образом? Давайте разберемся!

instruct
  1. Когда к вам на проект приходит новый человек, вы можете ему дать документацию, с помощью которой он сможет ознакомиться с вашим проектом. Обычно как бывает: приходит новый человек и к нему приставляют какого-то опытного коллегу. А теперь представьте что рейт этого человека 30 $/час. В тот момент, когда он что-то объясняет и вводит нового человека в курс дела, он полезной работы не делает, ну кроме как помогает потенциально будущему коллеге разобраться с тем барахлом, которое уже понаписано.

  2. Всем уже работающим на проекте это помогает быстро решать проблемы. Ну вот, скажем, когда я пришел 2 года назад на проект, я все настроил и работал себе - документация мне не нужна. Но тут вдруг у меня накрылась рабочая станция. Что делать? Всего в голове не удержать, как и с какими настройками Postgres ставить.

  3. Все проекты когда-либо заканчиваются. И в момент передачи знаний документация, а точнее ее отсутствие, начинает играть очень важную роль.

Да, обычно на проектах есть какая-то документация, она лежит в гуглдоках или каких-то абстрактных хранилищах. Вроде как все счастливы. Но основная проблема - это держать эту самую документацию в актуальном состоянии. Мне, к примеру, бывает сложно всегда помнить, в каком места и как у нас называется какой-то конкретный документ. Соответственно пойти и проапдейтить его я забываю. Знакомая ситуация, не правда ли?

Как же мы можем это поправить? Хранить документацию вместе с проектом! Да, именно так. Мы же каждый день работаем с нашими проектами, качаем сорс из гитхаба, пушим наши изменения. Почему бы не делать тоже самое с документацией к проекту?

Благо, для этого уже придумано огромное количество средств и инструментов.

Самое простое, что вы можете сделать, - это написать README.md к вашему проекту на Github. Опишите там Getting Started и это уже будет огромным шагом к прогрессу.

Но иногда хочется, чтобы документация была еще и красивой, со всякими там рюшечками! Это можно сделать, если последовать этому замечательному туториалу. Там все подробно описано, за исключением пары моментов, из-за которых у меня не работало с первого раза:

Tip
Когда будете связывать свой проект и Travis CI, то параметр GH_REF нужно указывать без http(s):// в формате github.com/SergeyPirogov/VideoRecorder.

Если вы все правильно сделаете, у вас после билда на тревисе в бранче gh-pages будет два файлика index.html и .pdf. Затем сразу же можно будет в браузере открыть эту документацию как простую веб-страницу: пример с рекордером.

Почему это круто?

  1. Все знают, где лежит дока.

  2. Ссылку на нее можно расшарить любому.

  3. Документацию легче поддерживать в актуальном состоянии, так как ее можно править из Github или же в вашей любимой Idea. Да что там, достаточно даже простого редактора по типу Vim.

  4. Вы можете легко отслеживать, кто и как изменял файл, так как вся история хранится в гите.

  5. Изменения автоматически будут пересобраны на Travis CI и документация на вашем условном сайте обновится практически моментально.

Лично мне этот подход очень понравился. Теперь я стараюсь применять его для всех своих проектов. Хорошей вам документации и до встреч…​

Частные консультации и обучение