Category Archives: единый источник документации

Техническая коммуникация и документирование ПО

Сегодня второй день Зимней Школы по программной инженерии для выпускников ВУЗов’11, на которой я представила свой доклад о технической коммуникации и документировании ПО. Презентацию можно посмотреть здесь:
Техническая коммуникация и документирование ПО.pps (PowerPoint 2003 file)

Advertisements

Leave a comment

Filed under CMS, Confluence, Документация, документирование ПО, единый источник документации, управление проектами, technical communication, technical writing, Wiki

I’m on SECR 2010!

This year I’m attending and speaking at the Software Engineering Conference taking place in Moscow, Russia.

The event is awesome. The key persons of the industry traditionally visit the event. Grady Booch, Ivar Jacobson, Lars Bak, Yuri Gurevich, Steve Masters are among the key speakers of the last years.

This time Bjarne Stroustrup comes to visit us at SECR (his program is here).

I’m looking forward to meet the icon!

My paper on ‘Supporting SaaS in Documentation Systems’ is submitted to the conference program. Yeah!

Now it’s time to prepare a presentation.

Leave a comment

Filed under CMS, Документация, документирование ПО, единый источник документации, IT conference, software documentation, tech writing, technical communication, technical writing, Wiki

Как документируют ПО?

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

Виды справки

Справка может быть контекстной или статической. Контекстная справка вызывается по нажатию клавиши F1 в приложении и автоматически открывает страницу с нужной информацией. Статическая справка – это просто документ, в котором последовательно изложена информация о продукте или API-функции. Справку по коду программы, структуры классов и описание их членов можно генерировать «изнутри» (из комментариев внутри кода), а можно «снаружи» (по отдельным описаниям функций и классов в формате XML, HTML, wiki markup).

По принципу единого источника

Часто бывает так, что требуется генерировать сразу несколько форматов справки:

  • Онлайн-справка для посетителей сайта
  • Контекстная справка внутри программы
  • Печатная документация

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

Для этого существует разные XML CMS и XML-схемы (DITA, DocBook), которые позволяют создавать, хранить и управлять XML-документами, из которых генерируется справка сразу нескольких форматов (разработаны соответствующие XSL-преобразования). Однако такие XML CMS довольно дороги, а XML-схема по умолчанию обеспечивает около 80% функциональности, требуемой техническому писателю для создания полноценной документации.

Вот некоторые XML CMS, которые можно использовать для ведения профессиональной документации, каждая из которых стоит порядка 10 – 100 тыс. долларов:

Horizon (http://www.inmedius.com)
XDocs (http://www.bluestream.com/products/xdocs10)
X-Hive/Docato, (http://www.x-hive.com/products/docato/index.html)
TEXTML Server (DITA CMS Framework) (http://www.ixiasoft.com)
Contenta (http://www.xyenterprise.com/)
SiberSafe (http://www.siberlogic.com/)

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

Справка в формате базы знаний

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

  • Генерацию документов по принципу единого источника из текста, хранящегося в wiki-системе:
  • Хорошую поддержку ЖЦ документа
  • Поддержание в актуальном состоянии документов
  • Средство сбора обратной связи от пользователей

Одной из самых мощных вики-систем на сегодняшний день является продукт австралийских разработчиков – Atlassian Confluence (http://confluence.atlassian.com/display/DOC/Confluence+Documentation+Home).

Неизбежное зло

  • ГОСТЫ. Ужасные требования к документации для программных систем. Приводят к накоплению большого количества бумаги, где суть переливается из пустого в порожнее. Рекомендуют никуда не годную структуру для описания работы с программным продуктом или системой. Но без них нельзя при разработке корпоративных систем для государственных структур.
  • Компромисс между автоматизацией справки и гибкостью дизайна. Чем лучше автоматизирован процесс документации, тем сложнее изменять структуру справки, менять внешний вид, оформление, настраивать дополнительные возможности отображения.
  • Чем актуальнее справка, чем быстрее она обновляется, тем хуже ее структура. С переменным успехом с этим можно бороться, взяв на вооружение хорошую wiki-систему.

Leave a comment

Filed under документирование ПО, единый источник документации, software lifecycle, tech writing