Какие документы необходимы на программные продукты

Документа́ция на программное обеспечение — печатные руководства пользователя, диалоговая (оперативная) документация и справочный текст, описывающие, как пользоваться программным продуктом[1].

Документ — элемент документации: целевая информация, предназначенная для конкретной аудитории, размещенная на конкретном носителе (например, в книге, на диске, в краткой справочной карте) в заданном формате[1].

Программная документация — документы, содержащие в зависимости от назначения данные, необходимые для разработки, производства, эксплуатации, сопровождения программы или программного средства[2].

Типы документации[править | править код]

Существует четыре основных типа документации на ПО:

архитектурная/проектная — обзор программного обеспечения, включающий описание рабочей среды и принципов, которые должны быть использованы при создании ПО
техническая — документация на код, алгоритмы, интерфейсы, API
пользовательская — руководства для конечных пользователей, администраторов системы и другого персонала
маркетинговая

Архитектурная/проектная документация[править | править код]

Проектная документация обычно описывает продукт в общих чертах. Не описывая того, как что-либо будет использоваться, она скорее отвечает на вопрос «почему именно так». Например, в проектном документе программист может описать обоснование того, почему структуры данных организованы именно таким образом. Описываются причины, почему какой-либо класс сконструирован определённым образом, выделяются паттерны, в некоторых случаях даже даются идеи как можно будет выполнить улучшения в дальнейшем. Ничего из этого не входит в техническую или пользовательскую документацию, но всё это действительно важно для проекта.

Техническая документация[править | править код]

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

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

Часто при составлении технической документации используются автоматизированные средства — генераторы документации, такие как Doxygen, javadoc, NDoc и другие. Они получают информацию из специальным образом оформленных комментариев в исходном коде, и создают справочные руководства в каком-либо формате, например, в виде текста или HTML.

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

Пользовательская документация[править | править код]

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

В случае если продуктом является программная библиотека, пользовательская документация и документация на код становятся очень близкими, почти эквивалентными понятиями. Но в общем случае, это не так.

Обычно, пользовательская документация представляет собой руководство пользователя, которое описывает каждую функцию программы, а также шаги, которые нужно выполнить для использования этой функции. Хорошая пользовательская документация идёт ещё дальше и предоставляет инструкции о том, что делать в случае возникновения проблем. Очень важно, чтобы документация не вводила в заблуждение и была актуальной. Руководство должно иметь чёткую структуру; очень полезно, если имеется сквозной предметный указатель. Логическая связность и простота также имеют большое значение.

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

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

Маркетинговая документация[править | править код]

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

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

Одна из хороших маркетинговых практик — предоставление слогана — простой запоминающейся фразы, иллюстрирующей то, что мы хотим донести до пользователя, а также характеризующей ощущение, которое создаёт продукт.

Часто бывает так, что коробка продукта и другие маркетинговые материалы дают более ясную картину о возможностях и способах использования программы, чем всё остальное.

Примечания[править | править код]

↑ 1 2 ГОСТ Р ИСО/МЭК 15910-2002 — Процесс создания документации пользователя программного средства
↑ ГОСТ 19781—90 Единая система программной документации. Обеспечение систем обработки информации программное

См. также[править | править код]

Unified Modeling Language

Ссылки[править | править код]

О документации на программное обеспечение

Источник

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

1.1. Выходные форматы

С выбором конечного формата обычно проблем не возникает, так как целевая операционная система предъявляет свои требования. Так, например, для программ для Windows — это формат скомпилированной справки CHM, для Linux и BSD систем — это man. Общим для всех систем форматом для онлайн справки является html, а для печати — pdf.

Ситуация осложняется в случае, если необходимо иметь документацию в нескольких форматах — для распространения с программой (chm или man), для размещения на сайте (html) и для печати (pdf). При этом возможно, что содержание документации в различных форматах может несколько отличаться. Например, видеофрагменты имеет смысл включать в онлайн документацию, а в печатной версии их нужно заменять на статическое изображение, возможно дополненным qrcode ссылки на видеофрагмент. Кроме того, содержание документов может отличаться и для различных категорий пользователей, версий, комплектов поставки и других факторов.

1.2. Исходные форматы

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

В зависимости от целевой операционной системы подходы отличаются.

1.2.1. Проприетарные исходные форматы

Так, для создания скомпилированной справки для Windows в формате chm Microsoft предлагает использовать специальный бесплатный компилятор HTML Help Workshop. При этом исходные тексты должны быть подготовлены в формате html (редактор в поставку не входит), а файлы оглавления — в специфическом формате. Никаких средств формирования печатных руководств не предоставляется.

Разумеется, специализированные программы для создания справки (Robohelp, Help&Manual, HelpScribble и им подобные) предоставляют высокий уровень сервиса, обладают возможностью формирования выходных документов в различных форматах и даже в некоторой степени профилировать содержимое.

Однако им присущи следующие недостатки:

Во-первых, все эти системы коммерческие и лицензируются по количеству используемых рабочих мест.
Во-вторых, используемый ими внутренний формат является проприетарным и не поддержимается никаким ПО, кроме продаваемого. Возможность импортировать файлы в проект вам, конечно, будет предоставлена, а вот экспортировать проект в какой либо открытый формат, пригодный для дальнейшей обработки, не удастся. Даже в случае использования в качестве внутреннего формата XML (как, например, Help&Manual) схема его остается закрытой и никак не задокументированной.
В-третьих, возможности по изменению внешнего вида выходного документа являются недостаточными для формирования, например, документации в соответствиями с требованиями ГОСТ.
В-четвертых, с этими программами организовать коллективную работу если и возможно, то крайне затруднительно

1.2.2. Простые форматы разметки
Рациональной альтернативой представляется применение простых и, как следствие, быстро осваиваемых форматов разметок.

На сегодняшний день таких форматов несколько:

ASCIIdoc, используемый дефакто в Linux (BSD) системах;
Wiki, применяемый в различного рода энциклопедиях и даже давший им общее название;
MarkDown — так сказать, «многоцелевой» формат документирования.

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

Например, Википедия преобразует Wiki-формат в HTML «на лету». Веб-портал системы Git https://github.org также способен показывать документы в разметке Markdown в пригодном для чтения в браузере виде.

1.3. Редакторы

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

В статье https://www.ixbt.com/soft/markdown-online-2.shtml приведен обзор онлайн-редакторов поддержкой markdown-синтаксиса, а в https://www.ixbt.com/soft/markdown-online-3.shtml приведен обзор пяти настольных редакторов, поддерживающих формат markdown по умолчанию, так сказать «из коробки».

Одним из таких редакторов является MarkdownPad.

1.3.1. MarkdownPad

Рисунок 1. Редактор MarkdownPad 2

Как видно из копии экрана, редактор MarkdownPad 2 поддерживает «живой» предварительный просмотр редактируемого файла с поддержкой синхронной прокрутки исходного текста и результата рендеринга.

При установке на Windows 8 может возникнуть ситуация, когда предварительный просмотр недоступен.

Рисунок 2. Сообщение о крахе системы предварительного просмотра

По заявлению разработчиков https://markdownpad.com/faq.html#livepreview-directx это связано с необходимостью установки специфического SDK веб-рендеринга Awesomium 1.6.6 SDK, который в свою очередь использует DirectX.

Редактор поддерживает подсветку синтаксиса, проверку синтаксиса одного языка (в том числе русского), экспорт в форматы HTML, PDF (только в платной версии). Иными словами, MarkdownPad 2, как и другие специальный редакторы, является хорошим выбором для технического писателя. В тех же случаях, когда пользователю предстоит редактировать файлы различного формата, можно адаптировать свой редактор и для редактирования текстов с markdown-разметкой.

1.3.2. Notepad++

Редактором, в достаточной мере отвечающим этим требованиям, можно считать Notepad++. Проверка правописания многих языков поддерживается с помощью специального плагина. Причем поддерживается проверка текста на нескольких языках одновременно.

Рисунок 3. Редактор Notepad++
Несмотря на простоту правил разметки, автору текстов было бы удобней работать с подсветкой синтаксических элементов. Применительно к Notepad++ в этом поможет проект Markdown Syntax Highlighting for Notepad++, который, по сути, представляет собой конфигурационный файл пользовательского языка Markdown. После его установки текст в редакторе выглядит следующим образом.

Рисунок 4. Редактор Notepad++ с подсветкой элементов разметки markdown

1.4. Quota

Примечательно, что редакторы с поддержкой markdown существуют даже для мобильных платформ. На рисунке приведена копия экрана смартфона с запущенным редактором Quoda Code Editor.

Рисунок 5. Quoda Code Editor — универсальный редактор для Андроид с поддержкой разметки markdown

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

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

1.4.1. Открытые теговые форматы

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

Этим требованиям в полной мере отвечают такие системы как DITA и Docbook.

Несмотря на некоторые различия, обе системы имеют много общего:

используют в качестве исходного формата документированный (схематизированный) XML, что обеспечивает возможность использования для редактирования любого XML-редактора с функцией валидации;
для конвертирования в один из результирующих форматов может быть использован практически любой xsl-преобразователь xslproc, xalan, saxon и др.;
для получения pdf-документа используется промежуточный формат xsl-fo, из которого средствами любого fo-процессора (например, Apache FOP или XEP) уже формируется pdf;
для настройки внешнего вида и профилирования используются многочисленные параметры преобразований, а в случае необходимости — добавлением пользовательских xsl-шаблонов.

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

Вместе с тем практический опыт использования, в частности Docbook, подтвержденный и в ряде публикаций, показал, что и при использовании столь продуманной технологии возникают некоторые сложности:

создание исходных текстов в формате XML определенной схемы требует от технического писателя навыков работы со специальными редакторами;
хорошие XML-редакторы с поддержкой Docbook — продукты коммерческие и недешевые (например, oXygen XML Editor, Altova XMLSpy XML Editor);
богатые возможности XML-разметки влекут за собой усложнение формата. Например, для вставки в текст иллюстрации с подписью в разметке Docbook необходимо использовать четыре вложенных тега.

Естественно, что вышеперечисленные недостатки сдерживают широкое применение XML-ориентированных технологий единого источника.

В случае использования нетеговых форматов для подготовки офлайн или печатной документации необходимо использовать утилиты преобразования. Среди многих конвертеров особого внимания заслуживает программа pandoc.

1.5. Утилита преобразования pandoc

Pandoc представляет собой кроссплатформенную программу с командным интерфейсом, способную преобразовывать тексты в самых разнообразных разметках в многочисленные выходные форматы.

Так, например с использованием pandoc можно конвертировать исходные документы в разметках ASCIIdoc, Wiki, Markdown в HTML. Если установить LaTex, то становится возможным получение и PDF.

Так, например, преобразование исходного текста этой статьи в html формат можно выполнить следующей командой:

pandoc -f markdown pandoc.md -t html -o pandoc.html -H h.html

Результатом будет готовый html-файл:

Рисунок 6. HTML-документ, сформированный из Markdown утилитой pandoc

За свою универсальность программа образно названа автором «швейцарским армейским ножом».

Действительно, pandoc справляется с конвертированием без каких-либо потерь информации. При конвертировании из формата MarkDown поддерживается чтение трех параметров метаданных — заголовка, автора и даты документа. Поддерживается также передача параметров командной строки для установки некоторых специфических свойств, например языка документа. Есть возможность задать свой шаблон выходного документа, до некоторой степени видоизменяя его.

Так, например, в приведенном выше примере подразумевается, что в текущей папке есть файл h.html, который играет роль заголовка. Если в этом файле добавить ссылку на стилевой файл и, определив <base target=”_blank”>, получим следующий результат:

Рисунок 7. HTML-документ, сформированный pandoc с использованием заголовочного файла со ссылками на стили

Как видно из примера, заголовки приобрели свой стиль, а внешние ссылки стали открываться в новой вкладке браузера.

Вышеописанные возможности формата делают оправданным использования разметки Markdown для документирования относительно небольших программных систем, к оформлению которых не предъявляется требований ГОСТ, что и доказывается ее широким использованием в системе Git.

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

1.6. Docbook

Сложность создания исходных XML-источников можно преодолеть путем использования исходных текстов в формате Markdown с последующим их конвертированием в Docbook. Такое преобразование поддерживается утилитой pandoc. Так, команда

pandoc -f markdown pandoc.md -t docbook -o pandoc4.xml -H h.xml

создаст результирующий файл.

Использование заголовочного файла h.xml (можно просто пустого) необходимо для корректной обработки метатегов и формирования статьи.

Рисунок 8. Сформированная статья в XML-редакторе

Следует отметить несколько дополнительных требований к разметки markdown, которая будет использована для преобразования в docbook:

Во-первых, следует избегать использования в тексте символов угловых скобок (< и >), так как в XML они используются для выделения тегов, а конвертер оставляет их как есть. Если же угловые скобки нужны по смыслу, то следует использовать сущности < и >.

Во-вторых, при вставке рисунка обязательно вводить альтернативный текст, так как pandoc использует его для создания обязательного тега title у тега figure.

Однако выходной текст формируется в устаревшем формате Docbook 4 версии, в то время как современная 5 версия предоставляет существенно более богатые возможности по семантической разметке.

Для преобразования текста из 4 в 5 версию можно воспользоваться специальным преобразованием db4-upgrade.xsl, входящим в комплект поставки Docbook.

xsltproc -o pandoc5.xml db4-upgrade.xsl pandoc4.xml

Полученный таким образом xml файл схемы docbook 5 можно использовать при формировании единого источника.

Рисунок 9. Cтатья схемы в XML-редакторе в режиме автора

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

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

Набор преобразований Docbook поддерживает формирование документов в HTML со стилями, PDF для печати так сказать «из коробки».

xsltproc -o pandoc5.fo c:<Путь к DocbookXSL>fodocbook.xsl pandoc5.xml

Внешний вид выходных документов может быть до определенной степени настроен с помощью параметров. Полученные файл формата FO-XSL pandoc5.fo является промежуточным и нужен для построения конечного PDF.

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

При большом количестве документов в составе пакета также возможно создание отдельного списка с возможностью автоматического формирования правильно оформленных ссылок на них. В случае же подготовки типографского макета руководства с учетом особых требований, например ГОСТ, необходимо разработать дополнительные xsl для форматов обычных страниц, титульной и финальной страницы.

Это может стать темой следующей статьи.

Источник