Недостатки инструментария wiki Голоса или обзор gitbook

Я попробовал поконтибутить в wiki проекта, поработал с используемым инструментарием gitbook, ощутил workflow и выявил определённые недостатки.

Описание инструментария

Для редактирования wiki используется онлайн-система http://gitbook.com.
По сути, gitbook представляет собой веб-редактор markdown, который использует git-репозиторий как бэкенд для хранения статей.

1. Высокий порог вхождения

Для того, чтобы внести изменения в wiki, требуется некоторое понимание работы с git и Pull Requests. Как правило всей этой кухней неплохо владеют программисты и прочие IT, но не рядовые пользователи.

Описание workflow

И так, чтобы вы сразу понимали, как построен процесс внесения правок в wiki сторонними участниками, опишу процесс:

Wiki лежит в репозитории на github. Нам нужно пойти туда и сделать форк репозитория.
Пойти на gitbook, создать новую книгу, в процессе создания указать, что мы хотим использовать имеющийся репозиторий на github.
gitbook создаёт клон уже нашего форкнутого репозитория у себя.
Мы делаем правки, жмём publish.
gitbook делает коммит локально + делает sync репо на github (т.е. git push по сути)
Мы идём в оригинальный репо wiki и жмём "Create new pull request"
Наши изменения мёржат.

Таким образом, разбираться с этой кухней желания ни у кого нет, ведь писать статьи на Голосе гораздо выгоднее и сытнее.

2. Непривычная модель для пользователей

Привычные wiki позволяют редактировать статьи "всем вместе" через единый веб-интерфейс. За счёт этого отсутствует проблема с разъезжанием репозиториев и необходимостью делать git rebase и разруливать конфликты. Здесь же мы имеем все эти прелести git.

Я не говорю, что git и распределённая модель правки это плохо. Наоборот, я приветствую это. Но тут мы подходим к следующей проблеме:

3. Ущербность gitbook

Предыдущие пункты могли бы быть сглажены хорошей системой редактирования, если бы она хорошо "скрывала" работу бэкенда и позволяла использовать мощь git. Однако, gitbook в этом плане слабоват.

gitbook заточен для работы с одним центральным репо, с которым просто работает несколько человек. Про распределённую модель (центральный репо и его форки) он ничего не знает, поэтому все мёржи, ребэйзы и pull requests вам надо делать ручками. Опять же, конфликты в случае чего вам придётся разруливать на локальной машине после git pull upstream. Тут уже стоит сказать, что даже не все девелоперы умеют хорошо работать с git rebase.
Встроенные Change Requests. В gitbook есть встроенный механизм "Change Requests". По сути это pull requests в рамках одного репо. Задумано так, что вы например создаёте "change request", при этом создаётся отдельный бранч, вы там вносите изменения, а потом аппрувите этот change request и бранч мёржится в мастер. Удобно для множества контрибуторов в одном репо, но в распределённой модели нахрен не нужно. Кстати, эти бранчи ломаются, если например после его создания запушить что-нибудь в master.
Ущербность встроенного файлового менеджера. Мы работаем с md-файлами, и хотим поддерживать какую-то структуру на файловой системе. В gitbook совершенно неочевидно, как и где создаются файлы под новые статьи. Возможно, отчасти из-за этого сейчас такой бардак в wiki, про который я писал в предыдущей статье.
Непрозрачный процесс сохранения изменений. Т.к. мы работает с git, то логично вносить изменения и перед коммитом смотреть git diff, дабы не накоммитить какого-нибудь непотребства. В gitbook мы перед "publish" ничего такого сделать не можем, мы не заметим, если помимо правки нужной статьи где-то тыкались и случайно удалили одну буковку например. Короче, мощь git-а незадействована. В десктопном редакторе кстати то же самое, по сути он ничем не отличается от онлайнового, набор функций тот же.

Вывод

gitbook плох для распределённой модели git. Лично я далее буду просто локально редактировать статьи без всякого gitbook удобным markdown-редактором.

Предложения

А может ну его нафиг, gitbook этот? (шутка)

В проекте на gitbook есть возможность добавлять collaborator-ов. Дать желающим доступ и пусть редактируют в своих бранчах (Change Requests), потом ответственный за wiki их Accept-ит. Будет примерно видно, кто чем занимается и удобнее разруливать конфликты (не межличностные, а те которые в git).
Выпилить gitbook и перейти на static renderer типа mkdocs. Отличная популярная штука, которую используют множество OSS-проектов для документации. Выглядит примерно вот так: https://docs.readthedocs.io/en/latest/getting_started.html - такая же модель с навигацией слева как и сейчас.