Одним из неотъемлемых этапов создания любого программного обеспечения является этап разработки документации [2]. К сожалению, нередко программисты совсем пренебрегают этим ответственным делом или относятся к нему крайне небрежно, а в результате многие нужные программы никем не используются или используются лишь отдельные (далеко не все) их возможности. При этом во много раз увеличиваются затраты машинного времени и труда программиста при необходимости установки и применения какого-нибудь программного продукта, когда приходится методом "проб и ошибок" находить способы работы с программой, определять ее возможности, ограничения и другие параметры.
Владение искусством разработки документации является зачастую одним из важнейших факторов, определяющих качество работы программиста.
Во-первых, умение создавать программную документацию определяет профессиональный уровень программиста. Заказчик не будет вникать в тонкости и особенности даже самой замечательной программы. Заказчик будет сначала читать документацию. Поэтому грамотно созданный пакет программной документации создаст у заказчика или работодателя самое что ни на есть благоприятное впечатление. Тем более, если автор программной документации будет избегать жаргонных выражений, за которыми обычно скрывается либо скудость мыслей, либо полная пустота.
Во-вторых, грамотно созданный пакет программной документации избавит разработчика от многих неприятностей. В частности, избавиться от назойливых вопросов и необоснованных претензий можно просто отослав пользователя к документации.
Конечно, разработка программной документации – творческий процесс, зависящий, в том числе, и от способностей автора документа, тем не менее, каждый программист должен (лучше или хуже) составить описание своей программы и научить других с ней работать.
Некоторую регламентацию деятельности в процессе подготовки документации дают стандарты Единой системы программной документации (ЕСПД). Четкое и грамотное освещение всех вопросов, предусмотренных ГОСТами, даст потребителю минимальное представление о назначении программного обеспечения, его возможностях, порядке работы с ним.
К программным относят документы, содержащие сведения, необходимые для разработки, изготовления, сопровождения и эксплуатации программ. Перечень этих документов определен ГОСТ 19.101-77 [3], но в данном пособии будут рассмотрены лишь некоторые наиболее важные из них, необходимые для достижения целей практики.
Хотя основная часть комплекса ЕСПД была разработана в 70-е и 80-е годы, однако в дальнейшем ГОСТы неоднократно пересматривались (иногда в них вносились незначительные изменения) и переутверждались.
Пользоваться стандартами следует умело, хорошо представлял себе цели и назначение каждого документа. При первом, обычно беглом, знакомстве со стандартами возникает ощущение, что во всех документах (а их довольно много) повторяются одни и те же положения. Следствием этого является простое повторение (раз уж ГОСТ требует) текста одноименных разделов во всех документах. Но такой подход в корне неверен, поскольку каждый документ предназначен для какой-то своей категории пользователей, а значит должен представлять программный продукт в несколько ином свете.
Более того, ГОСТы определяют только основные разделы документов, необходимые в любых программных разработках, они не отражают, да и не могут отражать, специфики каждой конкретной работы. Поэтому подходить к подготовке документа нужно творчески, не следуя слепо главным стандартам, а пользуясь предоставленным ГОСТом правом вносить новые разделы и дополнять стандартные новым содержанием. Нужно отметить, что стандарты ЕСПД (а также и Международный стандарт ISO/IEC) носят рекомендательный характер. Дело в том, что в соответствии с Законом РФ "О стандартизации" эти стандарты становятся обязательными на контрактной основе, т.е. при ссылке на них в договоре на разработку (поставку) программных систем.
Одна из причин низкого качества документации – ее несвоевременная подготовка, чаще всего все документы пишутся уже после завершения разработки, но детали быстро забывается, и чем больше времени прошло от создания программы до написания документа, тем меньше документ соответствует программе (многие тонкости и нюансы забываются). Выход здесь только один – параллельно вести разработку программного обеспечения и документации к нему. Редко кому удается сразу написать четкий лаконичный текст, ни разу не внося в него поправок, поэтому длительный период разработки документа создает предпосылки для многократного обращения к тексту, поиску более удачных определений, форм записи и т.п.
С другой стороны, серьезно работая над текстом документа, стараясь наиболее полно описать программу, программист часто обнаруживает какие-то недочеты в алгоритме, ошибки в выборе форматов данных, неточность в диагностических сообщениях и т.п.
Название документа должно состоять из двух частей: собственно названия программного продукта и наименования типа документа, например, "Редактор текста. Руководство оператора".
Требования к стилю документа можно сформулировать следующим образом: текст должен быть четким, понятным (!), исключающим возможность неоднозначного толкования, и, по-возможности, кратким. Т.е. в первую очередь следует стремиться к четкости и полной ясности. Лучше лишний раз подробно пояснить свою мысль, привести пример, чем о чем-то умолчать, считая, что это всем известно, но не следует и без необходимости "раздувать" текст документа. Чем лаконичней его содержание, тем легче его освоить и с ним работать.
Не следует увлекаться различными сокращениями, даже если вы к ним привыкли, т.к. для знакомящихся впервые с данной проблематикой чтение такого документа станет непосильной задачей. В этом случае в конце документа, как того требует ГОСТ, должен приводиться перечень сокращений.
Освещая различные положения, предусмотренные стандартом на каждый конкретный документ, нужно стремиться в первую очередь изложить специфичные для данной области вопросы.
В завершении необходимо обратить внимание на весьма распространенную ошибку при разработке программной документации. При описании программного продукта многие разработчики путают понятия компонента и комплекса. Это – разные виды программ (ГОСТ 19.101-77 [3]). Компонент определяется как "программа, рассматриваемая как единое целое, выполняющая законченную функцию и применяемая самостоятельно или в составе комплекса", а комплекс – это "программа, состоящая из двух или более компонентов и (или) комплексов, выполняющих взаимосвязанные функции, и применяемая самостоятельно или в составе другого комплекса".