Пользовательская документация. Лекция 30. Пользовательская документация.. Лекция 30. Пользовательская документация
 Скачать 26.42 Kb.
|
|
Лекция 30. Пользовательская документация. Документация на программное обеспечение — это документы, сопровождающие некоторое программное обеспечение (ПО) — программу или программный продукт. Эти документы описывают то, как работает программа или то, как её использовать. Документирование — это важная часть в разработке программного обеспечения, но часто ей уделяется недостаточно внимания. Существует четыре основных типа документации на ПО: 1. Архитектурная или проектная — обзор программного обеспечения, включающий описание рабочей среды и принципов, которые должны быть использованы при создании ПО. 2. Техническая — документация на код, алгоритмы, интерфейсы, API. 3. Пользовательская — руководства для конечных пользователей, администраторов системы и другого персонала. 4. Маркетинговая. Архитектурная, проектная документация. Проектная документация обычно описывает продукт в общих чертах. Не описывая того, как что-либо будет использоваться, она скорее отвечает на вопрос «почему именно так?» Например, в проектном документе программист может описать обоснование того, почему структуры данных организованы именно таким образом. Описываются причины, почему какой-либо класс сконструирован определённым образом, выделяются паттерны, в некоторых случаях даже даются идеи как можно будет выполнить улучшения в дальнейшем. Ничего из этого не входит в техническую или пользовательскую документацию, но всё это действительно важно для проекта. Техническая документация. Это именно то, что подразумевают под термином документация большинство программистов. При создании программы, одного лишь кода, как правило, недостаточно. Должен быть предоставлен некоторый текст, описывающий различные аспекты того, что именно делает код. Такая документация часто включается непосредственно в исходный код или предоставляется вместе с ним. Подобная документация имеет сильно выраженный технических характер и в основном используется для определения и описания API, структур данных и алгоритмов. Часто при составлении технической документации используются автоматизированные средства — генераторы документации, такие как Doxygen, javadoc, NDoc и другие. Они получают информацию из специальным образом оформленных комментариев в исходном коде, и создают справочные руководства в каком-либо формате, например, в виде текста или HTML. Использование генераторов документации и документирующих комментариев многими программистами признаётся удобным средством, по различным причинам. В частности, при таком подходе документация является частью исходного кода, и одни и те же инструменты могут использоваться для сборки программы и одновременной сборки документации к ней. Это также упрощает поддержку документации в актуальном состоянии. Пользовательская документация. В отличие от технической документации, сфокусированной на коде и том как он работает, пользовательская документация описывает лишь то, как использовать программу. В случае, если продуктом является программная библиотека, пользовательская документация и документация на код становятся очень близкими, почти эквивалентными понятиями. Но в общем случае, это не так. Обычно, пользовательская документация представляет из себя руководство пользователя, которое описывает каждую функцию программы, а также шаги, которые нужно выполнить для использования этой функции. Хорошая пользовательская документация идёт ещё дальше и предоставляет инструкции о том что делать в случае возникновения проблем. Очень важно, чтобы документация не вводила в заблуждение и была актуальной. Руководство должно иметь чёткую структуру; очень полезно, если имеется сквозной предметный указатель. Логическая связность и простота также имеют большое значение. Существует три подхода к организации пользовательской документации. Вводное руководство (англ. tutorial), наиболее полезное для новых пользователей, последовательно проводит по ряду шагов, служащих для выполнения каких-либо типичных задач. Тематический подход, при котором каждая глава руководства посвящена какой-то отдельной теме, больше подходит для совершенствующихся пользователей. В последнем, третьем подходе, команды или задачи организованы в виде алфавитного справочника — часто это хорошо воспринимается продвинутыми пользователями, хорошо знающими, что они ищут. Жалобы пользователей обычно относятся к тому, что документация охватывает только один из этих подходов, и поэтому хорошо подходит лишь для одного класса пользователей. Во многих случаях разработчики программного продукта ограничивают набор пользовательской документации лишь встроенной системой помощи (англ. online help), содержащей справочную информацию о командах или пунктах меню. Работа по обучению новых пользователей и поддержке совершенствующихся пользователей перекладывается на частных издателей, часто оказывающих значительную помощь разработчикам. Маркетинговая документация. Для многих приложений необходимо располагать рядом рекламные материалы, с тем чтобы заинтересовать людей, обратив их внимание на продукт. Такая форма документации имеет целью: подогреть интерес к продукту у потенциальных пользователей информировать их о том, что именно делает продукт, с тем чтобы их ожидания совпадали с тем что они получат объяснить положение продукта по сравнению с конкурирующими решениями Одна из хороших маркетинговых практик — предоставление слогана — простой запоминающейся фразы, иллюстрирующей то, что мы хотим донести до пользователя, а также характеризующей ощущение, которое создаёт продукт. Документация к продукту — это достаточно общее понятие; часто мы используем его, не уточняя, что именно подразумевается. Технические писатели, разработчики, тестеры и руководство видят проблему разработки описаний со своей стороны, поэтому иногда не могут договориться, чтобы создать общий полезный продукт. В идеале разработкой документации должно заниматься отдельное подразделение, тесно связанное с тестерами, разработчиками и, что важно, пользовательской аудиторией. В реальности даже в крупных зарубежных компаниях, годами оптимизирующих рабочий процесс, все работает не совсем так. О российских реалиях даже не говорю: работая техническим писателем в течение многих лет, мне практически не доводилось встречать организации, где бы при постоянном развитии крупного продукта документация была всегда полной, актуальной и понятной конечному пользователю. Руководству хочется снизить затраты, соответственно, они пытаются либо экономить на технических писателях, заставляя садиться за перо разработчиков, либо экономить на применяемых инструментах. В обоих случаях получается не здорово: разработчики не имеют такого ресурса времени (да и свободно выражаться на «письменном русском» в понятной для конечного пользователя форме могут лишь единицы), а экономия на инструментах приводит к документации в Word-е, которую потом практически не реально поддерживать в актуальном состоянии. Понятно, что мгновенно «неудачную» документацию невозможно превратить в «удачную». Но для понимания, в каком направлении следует развиваться, полезно представлять, какие для этого можно использовать инструменты. Издание TechRepublic предлагает свою классификацию способов документирования продуктов; представляю ее в несколько дополненном варианте. Комментарии в исходном коде. Когда термин «документирование» упоминается в среде разработчиков, скорее всего, имеется в виду добавление комментариев в исходный код. Но, с развитием программирования как такового, смысл таких комментариев частично потерялся (хотя, это не означает, что смысла нет совсем). Теперь у разработчиков есть возможность использовать более описательные имена переменных и модулей; кроме того, появились другие инструменты для документирования, так что комментарии перестали быть решением де-факто. Но до сих пор они имеют определенную ценность. С помощью комментариев можно кратко описывать логику работы фрагментов кода, давать ссылки на спецификации или внешнюю документации (в том числе страницы системы баг-треккинга). Однако стоит помнить, что их применимость должна быть ограничена стилем работы разработчика. К примеру, комментарии не должны использоваться для замены описательных имен переменных. «Самодокументирующийся» код. Благодаря системам, позволяющим присваивать функциям, классам и переменным более длинные имена, теперь гораздо проще создавать «самодокументирующийся» код, т. е. передать смысл их «существования» через названия, не прибегая к дополнительным комментариям. «Самодокументирование» - это, как и вопросы применимости комментариев, не способ создания документации, а рекомендации к стилю разработки. API для генерирования документации. Некоторые языки позволяют вставлять фрагменты более полной документации в исходный код (как правило, в формате XML); впоследствии могут использоваться автоматизированные инструменты для «упаковки» этих фрагментов в готовые файлы справки. Подобный подход полезен, но требует достаточно больших трудозатрат. Кроме того, не всегда можно получить от человека, разрабатывающего код, подробное описание принципа работы (ответы на вопросы «почему»), вместо простого примера синтаксиса. Документирование через системы баг-треккинга и системы управления проектами. В последнее время мир наводнили различные инструменты, помогающие разработчикам управлять проектами, учитывать ошибки и совместно заниматься их исправлением. Подобные системы позволяют снабжать отдельные элементы процесса разработки (модули, функции, ошибки и т. п.) огромным количеством метаданных, на основе которых менеджеры могут строить красочные графики и отчитываться перед руководством о «средней температуре по больнице» (точнее, о среднем времени, потраченном группой на решение стандартизованной проблемы, и т. п.). Некоторые системы позволяют хранить историю изменений кода в контексте стоявших перед разработчиками задач. Все это не является в прямом смысле «документацией» к продукту, но представляет собой некое хранилище информации, позволяющее быстро проследить связь определенных модификаций кода с запросами клиентов или обнаруженными ошибками, не разгребая сотни электронных писем, бумаг и файлов. Документирование через UML. UML представляет собой специальный язык для «графического» документирования проекта, предоставляющий инструменты для подготовки документов, диаграмм, блок-схем, отражающих рабочий процесс и т. п. Хотя по отношению к UML высказывается много критических замечаний, в определенных случаях он может служить отличным инструментом документирования. Хотя UML напрямую не связан с другой системой документирования, DocBook, ее бы я отнесла к этой же категории специальных средств создания пользовательских описаний. Как и UML, DocBook характеризуется сложностью внедрения с нуля и недостатком людей, свободно владеющих всеми возможностями. Зато, по сравнению со следующим пунктом классификации, позволяет вести разработку документации по той же технологии, что и создание самого программного продукта: разбивать текст на модули, контролировать их изменения и т. п. Статичная документация. К сожалению, этот тип документации слишком распространен. Описание некой зафиксированной версии продукта создается в текстовом редакторе в готовой для печати форме. Главная проблема такой документации — полное отсутствие инструментов контроля версий. Скорее всего, со временем вы получите несколько копий одних и тех же документов с плавающими между ними изменениями. Реклама |