Создание программной документации — важный этап, так как пользователь начинает свое знакомство с программным продуктом именно с документации. Для чего предназначен программный продукт, как установить программный продукт, как начать с ним работать — вот одни из первых вопросов, на которые должна отвечать программная документация (Installation Guide, Getting Started). Составлением программной документации обычно занимаются специальные люди — технические писатели (иногда программную документацию пишут сами программисты или аналитики). Этот этап является самым неприятным и тяжелым в программистской работе. К сожалению, обычно этому либо не учат совсем, либо в лучшем случае не обращают на качество получаемых документов должного внимания. Тем не менее владение этим искусством является одним из важнейших факторов, определяющих качество программиста.
Умение создавать программную документацию определяет профессиональный уровень программиста. Заказчик не будет вникать в тонкости и особенности даже самой замечательной программы. Заказчик будет сначала читать документацию. Большую роль играет в этом и психологический фактор.
Грамотно составленный (точнее, созданный) пакет программной документации избавит вас от многих неприятностей. В частности, избавиться от назойливых вопросов и необоснованных претензий можно, просто отослав пользователя к документации. Это касается прежде всего важнейшего документа — Технического задания. Можно напомнить о многомиллионном иске к компании IBM, который предъявило одно крупноеиздательство, не удовлетворенное качеством вычислительной техники и программного обеспечения. IBM суд выиграла только благодаря тому, что предъявила подписанное обеими сторонами Техническое задание. Было это давно, еще в 70-х годах 20 века, однако сути дела это не меняет. На Западе важность программной документации поняли давно, вместе с программным обеспечением поставляется целый пакет документации.
Вообще программную документацию можно разделить по отношению к пользователю на внутреннюю и внешнюю.
Внешняя — всевозможные руководства для пользователей, техническое задание, справочники; внутренняя документация — та, которая используется в процессе разработки программного обеспечения и недоступна конечному пользователю (различные внутренние стандарты, комментарии исходного текста, технологии программирования и т.д.).
Когда программист-разработчик получает в той или иной форме задание на программирование, перед ним, перед руководителем проекта и перед всей проектной группой встают вопросы:
- Что должно быть сделано, кроме собственно программы?
- Что и как должно быть оформлено в виде документации?
- Что передавать пользователям, а что — службе сопровождения?
- Как управлять всем этим процессом?
- Что должно входить в само задание на программирование?
На эти и другие вопросы когда-то отвечали государственные стандарты на программную документацию — комплекс стандартов 19-й серии ГОСТ ЕСПД.
Но уже тогда у программистов была масса претензий к этим стандартам. Что-то требовалось дублировать в документации много раз (как оказалось — неоправданно), а многое не было предусмотрено, как, например, отражение специфики документирования программ, работающих с интегрированной базой данных.
Прошло много лет, программирование происходит в среде совершенно новых технологий, многие программисты, работая в стиле drag-and-drop, могут годами не видеть текстов своих программ. Это не значит, что исчезла необходимость в их документировании. Вопросы о наличии хоть какой-то системы, регламентирующей эту сторону создания программных средств, продолжают задавать постоянно.