Проще, чем заметки на рулоне туалетной бумаги

Похоже, я нашел землю обетованную для каждого, кто занимается написанием и оформлением документации. Заметка посвящена команде русскоязычного сообщества LibreOffice.

Написание документации включает в себя три этапа:

• Написание или перевод самого текста (в данном случае это не так важно);
• Вычитка и редактирование;
• Оформление.

Все процессы по своему сложны и в них задействовано много людей. В нашем случае 2,5 человека, но сути это тоже не меняет. Даже если всем занимается один человек, его время и силы очень ценны.

При работе над документацией встает несколько проблем.

• Обеспечение совместной работы и контроль версий;
• Возможность работать в любом месте и на любом устройстве (смартфон, компьютер, кофеварка);
• Конвертирование документации в разные форматы (онлайн, PDF, Epub и другие).

И оказывается, есть способ сделать все этапы максимально эффективными и решить все проблемы. Достигается это за счет использования:

• Языка разметки ReStructuredText (рокировка с Markdown, суть та же) и любого удобного простого текстового редактора (вплоть до Блокнота... с ручкой);
• Python-Sphinx - генератор документации, который преобразует файлы в формате reStructuredText в HTML website и другие форматы (PDF, EPub и man);
• Git и GitHub - система контроля версий и репозиторий;
• readthedocs.org - бесплатный сайт для публикации и генерации документации, использующий Python-Sphinx и GitHub.

С помощью этих инструментов процесс написания документации становится таким:

1. Пишем каждую главу руководства в формает ReStructuredText и сохраняем в файле с расширением .rst (тонкости наименования файлов и прочее обговорим позже);
2. С помощью Python-Sphinx генерируем документацию в разные форматы (конкретно в HTML, Epub, PDF);
3. Выгружаем проект Python-Sphinx на GitHub;
4. Связываем readthedocs.org и репозиторий проекта на GitHub;
5. Получаем вот такую штуку - ПРОТОТИП

В итоге мы получаем онлайн-версию руководства с шикарнейшим поиском и оглавлением внутри.

Автоматическую генерацию в нужные форматы и простоту их скачивания.

И плюс ко всему, можно легко создавать по несколько версий руководства. В нашем случае подразумевается версия руководства, для каждой версии ЛО. Например, как тут. Да еще и с выбором языка!

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

Скачайте PDF и Epub в прототипе и посмотрите на их качество. Такого вручную в ЛО добиться очень сложно. Не нужны никакие шаблоны и прочие премудрости.

На мой взгляд, это лучшее, что можно было придумать для работы над документацией. В ближайшее время я занесу все наработки по Краткому руководству ЛО на сайт. А потом уже займемся вычиткой и прочими делами. Ну и конечно, напишу ман с подробным описанием процесса.