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

Создание программной документации – важный этап, так как пользователь начинает свое знакомство с программным продуктом именно с документации. Для чего предназначен программный продукт, как установить программный продукт, как начать с ним работать – вот одни из первых вопросов, на которые должна отвечать программная документация (Installation Guide, Getting Started). Составлением программной документации обычно занимаются специальные люди – технические писатели (иногда программную документацию пишут сами программисты или аналитики). Этот этап является самым неприятным и тяжелым в программистской работе. К сожалению, обычно этому либо не учат совсем, либо в лучшем случае не обращают на качество получаемых документов должного внимания. Тем не менее, владение этим искусством является одним из важнейших факторов, определяющих качество программиста.

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

Грамотно созданный пакет программной документации избавит разработчиков ПО от многих неприятностей. В частности, избавиться от назойливых вопросов и необоснованных претензий, отослав пользователя к документации. Это касается, прежде всего, важнейшего документа – Технического задания. Многомиллионный иск в 70–х годах 20 века, предъявленный к компании IBM крупным издательством о неудовлетворительном качестве вычислительной техники и программного обеспечения, был в суде выигран благодаря предъявленному подписанному обеими сторонами Техническому заданию.

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

Когда программист–разработчик получает в той или иной форме задание на программирование, перед ним, перед руководителем проекта и перед всей проектной группой встают вопросы: Что должно быть сделано, кроме собственно программы? Что и как должно быть оформлено в виде документации? Что передавать пользователям, а что – службе сопровождения? Как управлять всем этим процессом? Что должно входить в само задание на программирование?

На эти и другие вопросы когда–то отвечали государственные стандарты на программную документацию – комплекс стандартов 19–й серии ГОСТ ЕСПД. Но уже тогда у программистов была масса претензий к этим стандартам. Что–то требовалось дублировать в документации много раз (как оказалось – неоправданно), а многое не было предусмотрено, как,.например, отражение специфики документирования программ, работающих с интегрированной базой данных.