Программная документация — практика создания
Документация на программное обеспечение — это вечная головная боль менеджера проекта. Если она есть, качественная и адекватная — значит, она неоправданно дорога в создании.
Перечислим основные требования к системе документирования программного продукта. В подборе требований мы исходим исключительно из практических нужд. Тему стандартов на документы мы вообще не стремимся и не будем затрагивать.
Итак, система разработки документации должна предоставлять следующие возможности.
- Легкая возможность смены шрифтового и стилевого оформления текста
- Автоматическое построение оглавления и указателей
- Возможность коллективной работы над документацией
- Возможность экспорта в html-формат
- Возможность экспорта в PDF-формат
- Пригодность для построения типографского макета брошюры или книги
- Удобная работа с иллюстрациями, в том числе большого размера
- Удобная верстка таблиц
- Возможность компоновки из готовых частей разных сборок, включающих разные главы (или варианты глав) документации
- Наличие визуальной среды разработки документации как для Windows, так и для Linux
Некоторые пункты требуют пояснений. Так, коллективная работа над документацией в эрзац-варианте организуется путем примитивного деления текста на логические единицы с последующим разбиением на файлы. Каждый файл может редактироваться разными людьми, но не одновременно.
Полноценная групповая работа над программной документацией требует применения унифицированного стандарта разметки текстовых файлов, хранимых в системе управления версиями. Эта же система VCS обычно используется для исходных текстов проекта. Желательно наличие визуальных сред редактирования документации, но можно обойтись обыкновенным текстовым редактором.
Логотип LaTeX
Примером может служить использование CVS для хранения файлов и LaTeX в качестве текстового процессора. В это случае возможно одновременное редактирование одних и тех же разделов макета документации разными авторами.
Экспорт в html-формат необходим для создания онлайн-версии документации. В принципе, такой вариант может поставляться и на диске с готовыми программами. Для чтения необходим лишь браузер.
PDF-формат позволяет сделать документацию удобной для печати, а средства для чтения PDF-файлов имеются практически везде.
Виды документации
Документация на программное обеспечение грубо делится на проектную, методологическую и эксплуатационную.
Особенным видом документации является встроенная в софт или же «обыкновенная» справка.
Неустранимым противоречием в практике разработки программной документации является то, что лучше автора никто ее написать не сможет, но автор обычно писать документацию не хочет.
И если в качестве проектной и методической документации вполне могут послужить проектные документы (уж они-то точно должны существовать), то описание тонкостей реализации подсистем, описание работы с подсистемами, описание процесса установки и настройки приходится выбивать ногами и вытягивать клещами из разработчиков.
Технический писатель? А кто ему все это рассказывать будет, проверять написанное опять же? А сколько он стоит?
Теоретически, в проектах среднего размера можно пытаться скрестить технического писателя с тестировщиком. Если повезет.
Средства разработки документации — прагматичный подход
Для небольших объемов документации годится любой текстовый процессор, но Ворду я предпочту OpenOffice.org Writer. OpenOffice производит более приличные html-файлы и отлично умеет экспортировать тексты в PDF.
Однако на файлах с большим количеством графических иллюстраций OpenOffice начинает глючить.
При большой любви к искусству можно писать собственно html-текст, предварительно подготовив иллюстрации заданного размера. Но это не очень-то производительно. Надо отметить, что Microsoft производит средства для создания html-справки. Они довольно бедны по возможностям, но многим их будет вполне достаточно.
Популярен формат разметки текстов DocBook. Для него существуют редакторы и генераторы готовых текстов. Мне сам формат не нравится избыточностью тегов (в смысле, тем, что теги есть как открывающие, так и закрывающие) и некоторыми другими мелочами. В частности, средства, позволяющие без больших танцевальных сюит иметь html- и PDF-файлы на выходе, мы не отыскали.
В сухом остатке — TeX. Вернее, LaTeX в качестве препроцессора и TeX в качестве средства генерации PDF. Существуют и программы для генерации html-документации из файлов для LaTeX.
Всем требованиям к системам документирования LaTeX удовлетворяет. Надо, справедливости для, отметить не очень удобную работу с таблицами и иллюстрациями, но простые варианты таблиц и скриншотов не создадут проблем.
Наверное, в природе существуют специализированные системы документирования проектов и написания справки. Но скажите, так ли уж они необходимы?..
апреля 15, 2009 at 12:35
Рекомендую посмотреть также мой инструмент для написания документации
http://www.bulldoc.ru
написан на PHP, документация в текстовых файлах, так, что можете хранить ее в CVS&SVN, правка и предпросмотр без компиляции через веб-интерфейс. Вывод в один статический файл, в обычный статический сайт, в CHM. Навигация, как в DocBook.
августа 8, 2012 at 12:44
[...] софт у вас есть, написанный на 80 процентов, есть документация — готовая процентов на 20. Софт работает, [...]