ики Гитхаба — не для документации

Давно хотел поделиться небольшим наблюдением: я часто вижу, что люди хранят документацию в вики Гитхаба. Я считаю, что так делать нельзя. Ни в коем случае. Лучшее место для документации — сам репозиторий проекта. Аргументы:

  1. В вики нет синхронизации версии кода с версией документации. В вики текст всегда отображается самый актуальный, он не зависит от того, на какой коммит смотрят пользователи через веб-интерфейс. Поэтому, если возникает необходимость узнать какой был API у конкретной версии кода, придётся вручную пытаться найти в истории вики момент, когда её содержимое совпадало с нужной действительностью. Эта проблема не возникнет если документацию хранить в репозитории проекта: если взять нужный коммит (нужную ветку, нужный тег), то документация будет видна в том виде, в каком она была на тот момент.

  2. В вики сложнее поддерживать документацию в актуальном состоянии. Гораздо проще одновременно с написанием кода писать и тесты, и документацию, чем потом отдельно к ним возвращаться и где-то в отдельном месте их править. Если с самого начала проекта поддерживать в порядке тесты с документацией, то и проблем в дальнейшей работе с ними не возникнет, но если забросить это дело (что очень просто сделать, когда код отделён от остальных сущностей), то вступает в действие энтропия. И уменьшение количества действий, нужных для обновления документации, делает проще её поддержку. Когда не нужен лишний шаг — его не нужно делать и сложнее оступиться.

  3. Изменения в основном репозитории проще отслеживать, чем следить за вики. Если открыть вики на всех, можно случайно не отследить добавление кем-нибудь ошибочной информации; тогда как стандартный путь внесения изменений через пулл-реквесты — удобный и надёжный. И, наоборот, на коммиты проще подписаться, чем отслеживать происходящее в вики.

В итоге, я не вижу причин использовать вики для документации. Если кто-то сможет привести аргументы в пользу подобного положения дел — буду им рад. И если появится смысл использовать вики, я бы хотел предложить попробовать сделать это не совсем обычным образом. Вики в Гитхабе, в принципе, тоже отдельный репозиторий, а это значит, что его можно подцеплять сабмодулем к другому репозиторию. Соответственно, можно попробовать сделать вики сабмодулем к основному репозиторию с кодом — в этом случае мы решаем почти все проблемы, но получаем в нагрузку необходимость следить за сабмодулем. Но, возможно, оно того будет стоить.

Вы можете прокомментировать эту статью в Мастодоне.

Опубликовано с метками: #Blog