Добрый день.Являясь одним из разработчиков открытого проекта Embox, я часто слышал (в последнее время слишком часто) о том, что проект интересный, но поскольку документации нет, его невозможно использовать. Мы отвечали, что документация в каком-то виде есть, что мы всегда можем ответить на вопросы, что в крайнем случае можно попытаться разобраться самостоятельно, ведь проект открытый, но все это не подходило. Пришлось заниматься данной, очень неприятной для разработчиков, темой. Но естественно, статья не о том, что документацией заниматься “неприятно”! A о том, как мы сделали процесс разработки документации более комфортным. Ведь в любом более менее большом проекте, обязательно возникают вопросы, связанные с документацией.
Для тех, кому лень читать, сразу скажу, что в итоге мы пришли к разработке документации в формате markdown. Ну а тех, кому интересны детали, причины, почему именно markdown и какие есть плюсы и минусы у данного подхода, прошу под кат.
Начну с обоснования актуальности темы. Не только у Embox есть проблемы с документацией. Например, компания Google анонсировал аналог программы Google Summer Of Code (GSOC) для технических писателей Season of Docs. Компания Лаборатория Касперского проводит конференции для технических писателей. А компания Parallels публикует статьи на хабре о том, как писать документацию. Все это указывает, что тема важная и возможно незаслуженно обделенная вниманием.
В упомянутой выше серии статей разбирается правильное содержимое документации, я же хочу акцентировать внимание на процессе разработки документации, технологии, если хотите. Ведь для проекта с открытым исходным кодом, отличительной чертой является именно открытость как свойство процесса разработки. И нам хотелось создать процесс, который будет удовлетворять требованиям нашего проекта.
Небольшой экскурс в историю наших процессов разработки документации.
Когда-то проект располагался на googlecode. У нас было довольно приличное wiki, многие даже вспоминают про него, спрашивают, где его найти и просят перенести его на github, где проект располагается сейчас (или в другое доступное место). Wiki на googlecode было действительно удобным. Оно было мультиязычным и имело, на мой взгляд, больше возможностей, чем wiki на github. Но так получилось, что вместе с самим googlecode оно кануло в лету. Текущее wiki на github достаточно хорошо выполняет возложенную на него функцию донесения оперативной информации о проекте, но целостную документацию создать на данной платформе достаточно сложно.
Конечно, для любого проекта с открытым исходным кодом, необходима как оперативная (быстро доступная) документация онлайн, роль которого и исполняет wiki, так и целостная документация доступная оффлайн, ведь по ней гораздо легче понять суть и идеологию проекта. Кроме того сделать оффлайн поиск по единому документу, а не разрозненным wiki страницам, также гораздо проще.
Наверное, самым хорошим вариантом, который мне известен, является документация ARM. То есть онлайн документация, где есть поиск по всем разделам, но конкретный документ доступен для скачивания в pdf-формате. К сожалению, Embox пока еще не дорос до компании ARM по своим возможностям. Поэтому оффлайн-версию нам пришлось делать отдельно. Для этого мы использовали сервис Google Docs. Он удобен, поскольку: позволяет скачивать данные в разных форматах, вести совместную работу и имеет встроенную систему контроля версий. Мы перенесли часть информации с wiki, задали структуру, ведь целью разработки оффлайн-версии было создание целостной документации, и стали развивать несколько документов. Но достаточно быстро мы столкнулись с проблемами. Информация устаревала, данные с wiki не соответствовали данным с оффлайн-документации, и главное нам так и не удалось создать целостную документацию. Структура была, но поскольку не удалось добиться приличной обратной связи с пользователями, получилось, что в документации разобраться могут только ее создатели. Это конечно не проблема сервиса, но факт, как говорится, налицо. Нам пришлось искать другой подход к данной проблеме.
Затем мы попробовали просто перенести данные со старого wiki на wiki github, но и тут быстро столкнулись с проблемами. Мы обнаружили, что часть информации устарела, часть так и не была дописана, часть было непонятно как представлять в удобном для пользователя виде. Продолжая поиск решения проблемы, мы в какой то момент, даже рассматривали разработку документации в TeX-е используя git репозиторий, но быстро поняли что это уже перебор. Хотя свое влияние данная идея оказала.
Мы решили сформулировать, что же мы хотим от документации имеется в виду от процесса разработки документации, содержимое оставляем за скобками:
- Документация должна храниться в текстовом формате, поскольку предполагалось использовать git в качестве системы контроля версий
- Документация должна иметь онлайн (wiki) и оффлайн (отдельные документы, например, в pdf) версии
- Онлайн и оффлайн документация должны иметь возможность достаточно простой синхронизации
- Документация должна состоять из разделов (глав), которые можно разрабатывать или изучать отдельно, но из которых можно составить целостную документацию
Ни один из пунктов не противоречит использованию markdown, а он был интересен поскольку уже используется на wiki. Можно было, конечно, использовать другой формат и конвертировать его в markdown. Но после составления еще одного списка требований, на этот раз к возможностям добавлять различного рода контент (изображения, текст, форматирование) мы пришли к выводу, что markdown достаточно удовлетворяет всем нашим текущим потребностям. А первое же гугление на тему “markdown to pdf”, показывало, что варианты, перевести markdown в другие форматы существуют и достаточно популярны.
Есть несколько вариантов превратить markdown в pdf, но самым популярным безусловно является pandoc. Эта утилита, может превратить какой угодно текстовый формат в какой угодно текстовый формат. Кроме того она консольная. Поэтому не только привычна для нас, но и может быть встроена в скрипты для создания документации в различных форматах.
Мы определись с утилитой и стали думать над следующим маленьким вопросом который нам предстояло решить, а именно как сделать единый документ, а не много файлов pdf с разными главами, полученными из отдельных markdown файлов. Первое желание было просто “за-cat-ить” файлы (слить текст из различных файлов) в нужной последовательности, но оказалось все куда проще, pandoc сам прекрасно умеет работать со списком файлов. Это позволило нам также частично решить и задачу, что нужны различные документы, в которых содержимое может пересекаться. Например, мы генерим три документа и во всех трех содержится раздел краткое описание. Мы просто указываем этот файл в списке для pandoc для всех документов.
Похожий принцип мы применяем и для титульных листов где содержаться название документа и так далее. Мы просто создали файлы с шапками для каждого документа и включаем их первыми файлами в списке исходников для pandoc.
Как вы, наверное, догадались, это же (список различных файлов) решает проблему с мультиязычностью, мы просто указываем файлы с нужным языком.
О русском поговорим немного подробнее. При генерации pdf pandoc использует latex в качестве бэкэнда для рендеринга, спелл-чекера и так далее. По умолчанию кириллица не отображается и выводится ошибка о неведомом символе. Это решается очень просто, достаточно указать “babel russian”.
---
...
header-includes:
- \usepackage[russian]{babel}
---Нужно отметить, что правильнее указывать
---
...
header-includes:
- \usepackage[russian, english]{babel}
---А в тексте использовать latex-команды
\selectlanguage{russian}
\foreignlanguage{english}{ English text }Или
\begin{otherlanguage}{english}
Text in english
\end{otherlanguage}Но поскольку мы хотели сохранить “чистый” markdown для возможного переноса на wiki и оказалось, что для наших целей достаточно указание babel, то решили не усложнять и оставили как есть.
Конечно нам хотелось иметь не абы как отформатированные документы, а как минимум выглядящие единообразно. И тут нам опять помог latex. Дело в том, что поскольку pandoc использует latex, ему можно указывать latex-шаблоны. Делается это просто с помощью опции --template
pandoc --template=embox_pandoc.latex ...После того, как вы составили шаблон и указали его при генерации всех документов, получаются документы в более менее едином стиле. “Более менее” — поскольку есть несколько проблем, которые нам так и не удалось решить. Например, формирование единого блока кода. В markdown есть возможность задать единый блок кода, чтобы не форматировалось и возможно включалась подсветка синтаксиса. Но у нас получилось сделать только однострочные блоки. Это выяснилось после просмотра сгенеренного latex кода.
То есть бывали случаи, когда один и тот же блок размещался на разных документах немного по-разному.
Еще один момент, связанный с кириллицей, то есть использованием русского языка. Как уже сказано выше, для использования русского языка оказалось достаточно указать russian babel в шапке. Но мы столкнулись с некоторыми странностями, например, выделения жирным не было, и другие странности форматирования. Изначально мы грешили на то, что русский задается в шапках, а не в шаблоне. Стали изучать проблему. Оказалось, что по-хорошему нужно не только использовать
\usepackage[russian, english]{babel}\usepackage[T1,T2A]{fontenc}
\usepackage[utf8]{inputenc}Но даже проделав это, не получилось исправить ситуацию. Оказалось, что не все наборы шрифтов содержат все варианты отрисовки, в частности наши не содержат жирный (bold), курсив (italic) и так другие форматы. Поскольку не было простого решения проблемы, мы подумали и отложили проблему до лучших времен. Ну и так как нам хотелось использовать чистый markdown (то есть без указания команд latex), мы сделали общий шаблон для обоих языков, а указание про русский язык вынесли в заголовок.
Буквально пару слов скажу про интерфейс самого приложения. Поскольку, как я и говорил, консольные приложения лично нам очень привычны и легко упаковываются в скрипты. Собственно, интерфейс простой, можно конечно задать много опций, но для наших целей достаточно указать шаблон, список входных файлов и выходной файл.
pandoc --template=embox_pandoc.latex <title file> <list of input markdown files> -o <output file>На просторах интернета можно встретить, что для генерации pdf (или другого выходного формата) необходимо тип обработчика с помощью опции --pdf-engine=xelatex, но по умолчанию он и так используется, если выходной файл имеет расширение pdf. Поэтому нам и это не понадобилось.
Скрипты для сборки документации мы упаковали в Makefile, чтобы стало уж совсем привычно. И теперь для получения документации можно установив необходимое окружение просто вызвать
make [en][ru]В заключении нужно сказать пару слов о системе контроля версий. Принципа не усложнять (сохранять простым) мы пытались придерживаться во всем. И поскольку самым простым решением было использование отдельного репозитория на github, то мы так и сделали. Мы надеемся, что использование github позволит улучшить обратную связь с пользователями. Ведь как известно на github есть issues, в которых можно обсуждать недостатки и предлагать свои идеи и направления.
Данный процесс был начат недавно, по многочисленным просьбам трудящихся! Мы успели сделать английскую и русскую версии “быстрого старта”, а также первую версию русского руководства пользователя. Нам сам процесс показался более удобным, поэтому и делимся с общественностью.