Сразу дисклеймер: это рассказ про инструмент, который мы написали для себя и используем каждый день. Ссылку дам в конце, продавать не буду — расскажу про проблему и как её решали, потому что упираемся в неё, возможно, не только мы.
За последний год мы переписали почти всю проектную документацию в markdown и положили в тот же git, где лежит код. Причина простая: после перехода на Cursor и Claude Code так было удобнее работать. Модели нормально обрабатывают markdown и не лопатят десятистраничный google-док, диффы видно в PR, доки лежат рядом с кодом, который описывают. Всегда можно обратиться к инфе по проекту, внести обновления - короче пользоваться документом, а не хранить его для красоты.
И тут вылезла проблема, о которой лично мы заранее не подумали: документацию читает не только тот, кто её пишет. Её читают клиенты, менеджеры, дизайнеры, эйчары. А они в репозиторий не полезут никогда.
Дать клиенту доступ в GitHub/GitLab — так себе затея сразу по нескольким причинам: там лежит то, что ему видеть не надо, это лишний разговор про безопасность, да и сам интерфейс гитхаба человека не из айтишки отпугивает. Плюс требуется регистрация. В итоге мы делали то же, что, по-моему, делают все: копировали markdown в google docs, чтобы клиент мог прочитать и покомментировать, а потом при каждом изменении заново выгружали и сводили комментарии руками. Год так жили.
Что смотрели, прежде чем пилить своё:
GitBook и Mintlify хотят, чтобы ты писал в их редакторе. Ради шеринга пришлось бы бросить тот самый workflow, ради которого мы в git и переехали. Плюс ценник.
