Существует множество подходов для создания документов. В первую очередь при выборе инструмента необходимо ответить на ряд вопросов.
- В каких форматах предоставлены исходные данные?
- В каких форматах должны быть выходные данные?
- Как должен быть оформлен документ?
- Необходимо ли использовать рисунки, графики, таблицы, аудио- и видеофайлы?
- Кто будет использовать документацию?
Важно понимать, будет ли инструмент для создания документации поддерживать импорт исходных данных. Исходные данные могут быть представлены в различных форматах (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»
При выборе инструмента для разработки документации следует учитывать форматы исходных и выходных данных, специфику оформления документа (шрифтовое оформление, дополнительные визуальные элементы и т.п.), знания и навыки технического писателя, а также будущего пользователя документации.