В чём разрабатывать программную документацию?

Существует множество подходов для создания документов. При выборе инструмента первостепенно необходимо ответить на вопросы:

• В каких форматах предоставлены исходные данные?

• В каких форматах должны быть выходные данные?

• Как должен быть оформлен документ? Необходимо ли использовать рисунки, графики, таблицы, аудио- и видеофайлы?

• Кто будет использовать документацию?

Важно понимать, будет ли инструмент для создания документации поддерживать импорт исходных данных. Исходные данные могут быть представлены в различных форматах (PDF, DOC, HTML, MD и др.).

Следует также учитывать, где будет размещен готовый документ. Для размещения в сети Интернет используется формат HTML, для печати применяется формат PDF, для программ Windows – CHM, для Linux – man. Иногда требуется выводить документацию сразу в нескольких форматах. Такой подход усложняет процесс подготовки, но дает возможность создания более полной и понятной для пользователя документации. Например, в онлайн-документах текст можно дополнить видеофрагментами, в печатной продукции – рисунками, графиками, а также QR-кодами для перехода на видеофайл.

Необходимо также определить будущего пользователя документов. Разработчик с легкостью прочитает Docs as Code, что составит проблему для пользователя приложения, не обладающего специальными знаниями.

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

• документация в текстовых редакторах;

• документация в Wiki-системах;

• Docs as Code;

• интерактивная документация.

В России чаще всего документация представлена в печатном виде, поэтому наибольшую популярность в процессе ее подготовки получили текстовые редакторы с возможностью экспорта в PDF-файл. При упоминании словосочетания «текстовый редактор» первым в голову приходит Microsoft Word. У этой программы существуют аналоги – LibreOffice Writer, Google Docs. Кроме того, документацию можно писать при помощи Markdown – облегченного языка разметки. Знания синтаксиса Markdown позволят техническому писателю создавать документы в таких текстовых редакторах, как iA Writer, Typora, Ulysses и др.

«Ulysses»

При участии в разработке документации одновременно нескольких специалистов удобными будут Wiki-системы. Как правило, Wiki имеют набор шаблонов страниц и встроенные инструменты для систематизации, а также поддерживают контроль доступа и учет изменений. Популярностью пользуются Confluence, GitBook, Evernote, Notion, DropBox Paper.

«GitBook»

Подход Docs as Code предполагает разработку документации при помощи языка разметки. В качестве языка можно использовать Markdown, reStructuredText или Asciidoc. Документация хранится в репозиториях Git, что позволяет контролировать её изменения. При данном подходе документы можно собрать одновременно в несколько форматов (DOXC, HTML, PDF и др.) при помощи генераторов статических сайтов. Такой подход расширяет возможности технического писателя, но требует больших знаний и навыков от технических писателей (знание языков разметки, навык работы с репозиториями Git).

Популярность получают инструменты для создания интерактивной документации. В данном случае речь идет об эксплуатационных документах. Преимущество такого подхода заключается в возможности виртуального отображения последовательности действий (анимации, 3D-модели и видеоролики). Интерактивную документацию можно разрабатывать в SolidWorks и Dr. Explain.

«Dr.Explain»

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