О документации

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

К тому же не стоит исключать фактор автобуса. При наличии документации исчезновение разработчика все же менее болезненно. Интуитивно это понимают все, и я много раз наблюдал, когда последние две недели работы бедный сотрудник документирует все то, над чем работал предыдущие два года.

Конечно, лучшая документация — это код. С этим я абсолютно согласен. Вот только лучшая она по показателю «полноты». А вот по показателю «читабельности» — она одна из худших. Дело тут даже не в том, хороший или плохой код. Даже если код хороший, не все умеют его читать.

Вот мне, например, как архитектору, приходится разбираться, как код на JavaScript формирует JSON-RPC вызов через WebSocket, все это доходит до Java, где вызывается процедура на PL/SQL, которая уже и модифицирует актуальные данные. Все эти нюансы можно прочесть в коде. Вот только читать надо на трех упомянутых языках. И далеко не все это могут, как оказалось. (А потом еще JetBrains удивляется, зачем мне нужна поддержка Objective C в IntelliJ IDEA).

Так что, кроме кода, нужна еще и документация на человеческом языке. Причем в первую очередь хочется видеть документацию о вызовах, о публичном API. Ибо именно это есть взаимодействие компонентов вашей системы. Возможно, то самое, ради чего её и создавали.

Яве повезло. В ней есть JavaDoc. Ну, в общем-то, подобные штуки есть для всех приличных языков. А для документирования, например, REST API, существуют свои инструменты. К сожалению, все эти штуки часто ограничены своими языками и платформами. И построить сквозную документацию не получится.

Поэтому я все же предпочитаю, чтобы публичное API документировалось вручную. Все же публичное API — это сильно меньше, чем все публичные методы всех классов ;)

Описание API отнесем к Спецификациям. Описанию того, что уже сделано и как оно уже работает. А еще есть Требования. То самое ТЗ (Техническое Задание), имея которое, Программист перевернет Землю.

Тут наблюдается интересная трансформация. Требования пишутся словами «следует», «необходимо», «должен», в будущем времени. Теми самыми формами модальности, прекрасно описанными в RFC 2119. Хорошо RFC, они как раз и описывают, как должна функционировать будущая сферическая система, которая реализует данный стандарт. А вот Спецификации пишутся в настоящем времени и безо всякой модальности.

И вот наступает некий момент (растянутый на все время разработки :), когда Требования превращаются в Спецификации. То, что необходимо сделать в будущем, становится реализованным настоящим. Как выразить этот переход в документации (и надо ли вообще), я еще не придумал. То ли сразу писать Требования, будто они уже сделаны. То ли Требования должны оставаться Требованиями, а Спецификации конкретной реализации оставаться Спецификациями.

А еще есть другие виды документов. Например, менеджерские. Результаты митингов, заполняемые чеклисты и прочее и прочее. Их тоже надо где-то хранить.

Я вообще стараюсь все записывать. Ничего не хранить в голове дольше двух дней. Как только какая-то проблема сформулировалась — записать. Как только придумали кучу способов решения проблемы — записать. Как только выбрали наиболее приемлемый способ и придумали, как его запилить, — записать. Вспоминая фактор автобуса. Да и просто, чтобы не нагружать сильно моск.

Любопытно, что в ходе таких мозгодампов рождаются документы, не очень похожие на приличную документацию. (А иногда и посты в блог :) Это описания экспериментов, сравнение различных технологий и решений, муки выбора. Совсем совсем не то, что выйдет в продакшен. Но я считаю, что такие вещи тоже нужно хранить. Чтобы ответить потом на вопрос: «А почему так, собственно?»

Мы юзаем Confluence. Самая лучшая Wiki из тех, что я использовал. Хоть и платная. И со своими странностями. Например, зачем перешли на WYSIWYG вместо вики разметки, мне не очень понятно. Но — не напрягает.

Кстати, как язык разметки что-то в последнее время сильно предпочитаю Markdown. Если кто подскажет хорошую wiki с Markdown разметкой, скажу спасибо.

А вот для диаграммок лучше PlantUML ничего не знаю. Но про это я уже писал. От wiki лишь хочется прозрачной интеграции PlantUML в любой документ.

Впрочем, иногда у wiki не хватает интерактива. Все хорошо, пока один документ редактируется одним человеком. Но когда нужно писать вместе и одновременно, да еще и оставляя по тексту комментарии... Тут помогает Google Drive. Все же совместное онлайн редактирование — это круто. Но в Google Drive очень туго со структурой (папки — неудобны) и ссылками (ссылка на документ — нечитаема). Тут ближе к классическому вебу, где каждый документ сам по себе. В wiki же документы ближе друг к другу. Да, хочу wiki движок с возможностью одновременного онлайн редактирования :)

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