Отправляет email-рассылки с помощью сервиса Sendsay

Полезные советы по автоматизации малого бизнеса

Рассылка закрыта

При закрытии подписчики были переданы в рассылку "Свой Бизнес: идеи, советы, секреты" на которую и рекомендуем вам подписаться.

Вы можете найти рассылки сходной тематики в Каталоге рассылок.

←   Декабрь 2008   →
 1
 2
 3
 4
04.12.2008
14:02:25
14:14:50
 5
 6
 7
 8
 9
10
10.12.2008
11:28:35
12:40:35
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
Автор
Smbiz.Narod.Ru

Статистика

384 подписчиков
0 за неделю
←   Все выпуски   →

Полезные советы по автоматизации малого бизнеса: Практика создания программной документации


Программная документация - практика создания


  • Уровень сложности: Для специалистов

Документация на программное обеспечение - это вечная головная боль менеджера проекта. Если она есть, качественная и адекватная - значит, она неоправданно дорога в создании.

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

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

  • Легкая возможность смены шрифтового и стилевого оформления текста
  • Автоматическое построение оглавления и указателей
  • Возможность коллективной работы над документацией
  • Возможность экспорта в html-формат
  • Возможность экспорта в PDF-формат
  • Пригодность для построения типографского макета брошюры или книги
  • Удобная работа с иллюстрациями, в том числе большого размера
  • Удобная верстка таблиц
  • Возможность компоновки из готовых частей разных сборок, включающих разные главы (или варианты глав) документации
  • Наличие визуальной среды разработки документации как для Windows, так и для Linux

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

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

Логотип LaTeX

Логотип LaTeX

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

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

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

Виды документации

Документация на программное обеспечение грубо делится на проектную, методологическую и эксплуатационную.

Особенным видом документации является встроенная в софт или же “обыкновенная” справка.

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

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

Технический писатель? А кто ему все это рассказывать будет, проверять написанное опять же? А сколько он стоит?

Теоретически, в проектах среднего размера можно пытаться скрестить технического писателя с тестировщиком. Если повезет.

Средства разработки документации - прагматичный подход

Для небольших объемов документации годится любой текстовый процессор, но Ворду я предпочту OpenOffice.org Writer. OpenOffice производит более приличные html-файлы и отлично умеет экспортировать тексты в PDF...

дочитать: Программная документация - практика создания

Еще по теме
В избранное