MetaGuide

Руководство для разработчиков технической документации к программному обеспечению

Настоящее Руководство носит характер корпоративного учебного пособия: оно, в первую очередь, адресовано разработчикам технической документации (см. Примечание 1) - сотрудникам фирмы "Философт"; однако оно может оказаться полезным всем, кому приходится так или иначе заниматься разработкой документации. Мы стремились свести в единую систему всю совокупность типовых требований, которые должны, с нашей точки зрения, предъявляться к технической документации: руководствам, справочникам и т.д. При этом мы основывались на стандартах ГОСТ, стандартах компании Microsoft, опыте наших сотрудников и других разработчиков технической документации. На этой основе сложилась система стандартов и требований, которые ныне приняты в фирме "Философт". Эту систему мы хотели бы предложить вниманию не только наших сотрудников (для них она имеет нормативное значение), но и всех вообще разработчиков технической документации на русском языке.

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

• Систематизация стандартов и требований помогает:

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

Наконец,

• Заказчик получает не произвольным образом написанный текст, а профессионально подготовленный, четко организованный на всех уровнях его структуры, стандартизированный документ.

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

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

Корпоративный стандарт - обязательное для сотрудников фирмы "Философт" требование, предъявляемое к описанию отдельных элементов программного продукта, структурирования текста, оформления и т. д.

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

• Во-первых, он позволяет унифицировать продукцию фирмы "Философт", что особенно важно при долгосрочной работе с постоянными клиентами: пользователь (см. Примечание 2), уже встречавшийся на практики со стандартами фирмы, увереннее чувствует себя при работе с очередным документом.
• Во-вторых, он убеждает заказчика, а впоследствии - пользователя в том, что за созданным документом стоит не только авторитет отдельно взятого "технического писателя", но и накопленный отечественным, если угодно, и авторитет официальных инстанций.
• В-третьих, он значительно облегчает работу самого технического писателя и экономит его время, позволяя в целом ряде случаев не задумываясь использовать готовые решения.

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

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

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

Если в документе усматривается какое-либо несоответствие корпоративному стандарту (стандартам), это несоответствие подлежит не обсуждению, а безоговорочному исправлению. Если же документ не вполне отвечает какому-либо критерию качества, это означает, что, возможно, этот документ не оптимален с точки зрения его чтения, восприятия, использования в работе и пр. Имеет смысл проверить это и поискать другое, более удачное решение, - соображаясь с конкретным контекстом, с конкретными целями документации и предполагаемыми обстоятельствами ее использования. Итак, критерии применяют тогда, когда надо сказать, чту именно в данном тексте не так. В этом случае говорят, что этот текст не соответствует тому или иному критерию качества.

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

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

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

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

Однако стандарты и критерии качества сами по себе недостаточны для организации работы над документацией. Стандарты описывают лишь часть ситуаций; критерии качества вообще не содержат предписаний, как именно следует писать. Необходим значительный массив методических указаний, которые бы позволяли систематизировать и оптимизировать рабочий процесс: с какой точки зрения подходить к материалу, как его располагать, какие стандарты и в каких ситуациях применять, как корректировать свою работу с точки зрения тех или иных критериев качества. Эти методические указания и представлены в настоящем Руководстве. Наиболее важные из них выделены в особую рубрику. Мы условно называем их рекомендациями.

Рекомендация - методическое предписание, которое может помочь систематизировать и оптимизировать процесс создания документации, соответствующей стандартным требованиям.

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

• Стандартные методики - это методики, применяемые в целом ряде (типичных) случаев для эффективного взаимодействия между участниками совместной работы над документом, оптимизации рабочего процесса, тестирования и отслеживания ошибок и пр.

Стандартные методики могут быть рекомендованы всем разработчикам и группам разработчиков документации. В фирме "Философт" эти методики в обязательном порядке включаются в сценарий рабочего процесса.

Стандартные методики составляют особый раздел в корпусе корпоративных стандартов фирмы "Философт".

Примечания

1. В обиходе, за неимением лучшего, используется неуклюжее, но точное словосочетание "технический писатель", являющееся пословной калькой английского technical writer.
2. "Пользователь" - это общепринятый термин, который, однако, не всегда удобен. Он может вызывать терминологическую путаницу, поскольку, когда речь идет, например, о сетевых продуктах, пользователем называется рядовой пользователь, в отличие от системного администратора: "Пользователь сообщает о своих проблемах системному администратору" и пр. В настоящем Руководстве (там, где не оговорено обратное) пользователем называется непосредственный потребитель программного продукта, будь то рядовой пользователь, администратор и т. д.