Смартсорсинг.ру

Сообщество руководителей ИТ-компаний, ИТ-подразделений и сервисных центров

Статьи в блогах Вопросы и ответы Темы в лентах Пользователи Компании Лента заказов Курс по ITSM

Идеальная и реальная документация программных продуктов

Идеальная и реальная документация программных продуктов

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

Руководству хочется снизить затраты, соответственно, они пытаются либо экономить на технических писателях, заставляя садиться за перо разработчиков, либо экономить на применяемых инструментах. В обоих случаях получается не здорово: разработчики не имеют такого ресурса времени (да и свободно выражаться на «письменном русском» в понятной для конечного пользователя форме могут лишь единицы), а экономия на инструментах приводит к документации в Word-е, которую потом практически не реально поддерживать в актуальном состоянии.

Понятно, что мгновенно «неудачную» документацию невозможно превратить в «удачную». Но для понимания, в каком направлении следует развиваться, полезно представлять, какие для этого можно использовать инструменты. Издание TechRepublic предлагает свою классификацию способов документирования продуктов; представляю ее в несколько дополненном варианте.

Комментарии в исходном коде

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

«Самодокументирующийся» код

Благодаря системам, позволяющим присваивать функциям, классам и переменным более длинные имена, теперь гораздо проще создавать «самодокументирующийся» код, т.е. передать смысл их «существования» через названия, не прибегая к дополнительным комментариям. «Самодокументирование» - это, как и вопросы применимости комментариев, не способ создания документации, а рекомендации к стилю разработки.

API для генерирования документации

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

Документирование через системы баг-треккинга и системы управления проектами

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

Документирование через UML

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

Хотя UML напрямую не связан с другой системой документирования, DocBook, ее бы я отнесла к этой же категории специальных средств создания пользовательских описаний. Как и UML, DocBook характеризуется сложностью внедрения с нуля и недостатком людей, свободно владеющих всеми возможностями. Зато, по сравнению со следующим пунктом классификации, позволяет вести разработку документации по той же технологии, что и создание самого программного продукта: разбивать текст на модули, контролировать их изменения и т.п.

Статичная документация

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

По материалам TechRepublic.

Дополнительные материалы

Комментарии (5)

  • Аватар

    Рубинштейн Кирилл [krubinshteyn], 20 сентября 2011, 16:11

    1
    Думал, что речь пойдет как в заголовке — о документации программных продуктов. А на деле все свелось к документированию кода.

    На самом деле, технические писатели есть много где, в том числе и у нас. Но проблема документации не в косности слов, и не в неполноте. А в отсутствии понимания у человека, который её пишет, о том, для чего документация нужна. Посмотрите примеры мануалов на софт. То, что там описано, можно описать уже классической фразой: "Как приготовить бублик диаметром 10 см? Надите форму для бублика диаметром 10 см, залейте туда тесто, поставьте в духовку". Само-собой, если вы не знаете как приготовить тесто для бублика, ничего у вас не выйдет.

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

    К сожалению, таких вот идеальных документаций я ещё не встречал.
  • Аватар

    Бушмелев Юрий Юрьевич [Jay], 20 сентября 2011, 23:08

    0
    На своем прошлом опыте сисадмина и программиста могу сказать, что понимание необходимости написания документации приходит очень быстро. Достаточно пару раз попытаться что-то поменять в коде, который написал полгода назад и больше с тех пор не видел. Сразу возникает желание документировать в коде хотя бы неочевидные моменты.

    Но документация кода - это всего лишь часть "айсберга". Необходимо писать инструкции для пользователя и для администратора системы. Мне повезло, я могу писать документацию. Если ваши программисты не обладают литературными навыками, нанимайте технического писателя. Технически, рекомендую вести документацию в wiki. Собственно, других вариантов я и не вижу.

    В целом, считаю, что документирование - это вопрос дисциплины в организации. Например, пока у меня только один клиент, который имеет внутреннюю документацию и держит ее в актуальном виде. Это позволяет новым сотрудникам быстро разбираться с тем, как построены бизнес-процессы в организации. Но я вижу тут нишу для бизнеса :)
  • Аватар

    Алёхин Владимир [avv], 22 сентября 2011, 14:49

    0
    У нас в проектах за документирование на всех его этапах отвечали аналитики. А использование системы Enterpise Architect помогало им это задачу успешно решать. Таким образом, весь проект от бизнес-требований и до тест-кейсов был как на ладони у ПМ-а, а заказчик наслаждался ненавязчивой документацией с красивыми uml-схемами и правильно расположенными комментариями. Удачи в документировании - вещь хорошая, если не перебарщивать.
  • Аватар

    Брагинский Матвей [MatveiBrag], 26 сентября 2011, 11:22

    0
    Конечно, документация необходима. В системе ГОСТ 24 или ГОСТ 19  есть руководства пользователя, рук-во программиста, рук-во системного программиста. Последнее ныне лучше назвать руквоводством администратора. 
    Если рук-во программиста , как описание алгоритма и программногого кода, еще можно заменить хорошо документированным (?)  программным кодом, то оставшиеся 2 документа заменить нельзя ничем.  И неважно, в электронном (хелп) виде они  или в бумажном, важна содержательность и актуальность.
    Грамотное сопровождение  ПО подразумевает актуализацию документации. Но кто и как её пишет?
    Согласен, что  "разработчики не имеют такого ресурса времени (да и свободно выражаться на «письменном русском» в понятной для конечного пользователя форме могут лишь единицы)", 
    но писать -то надо. Люди увольняются, кто-то принимает к сопровождению действующую систему  .  А значит одно из двух : либо учить писать  разработчиков, либо нанять техрайтера. НО  В любом случае подготовка и тестирование документации должно входить в процесс проектирования и сдачи системы в эксплуатацию.