Стайлгайд для программной документации

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

Дословно фразу «Style guide» можно перевести как «руководство по стилю». Стайлгайд представляет собой свод правил и требований к оформлению и структуре документации, включающий особенности тона изложения и использования терминологии. Кроме программной документации стайлгайды применяют в веб-дизайне, а также при разработке фирменного стиля компании, в оформлении книг и печатной продукции.

В англоязычном сегменте сети Интернет довольно легко найти примеры стайлгадов таких компаний, как Google, Microsoft, Skype и т.д. Подобные руководства помогут только в разработке документов на английском языке.

В России же практика применения стайлгайдов менее распространена. Информацию о структуре и содержании документации можно найти в требованиях ГОСТ (серий 2, 19 и 34). Помощником при оформлении документов также служит «Справочник издателя и автора» А. Мильчина и Л. Чельцовой. Для корректного выбора стилистически подходящих слов можно обращаться к «Справочнику по правописанию и стилистике» Д. Розенталя, а также толковым словарям и словарям синонимов.

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

Наличие стайлгайда в компании позволяет:

• привести документацию к единому виду, достичь целостности и согласованности текстов документов;
• ускорить адаптацию новых сотрудников;
• ускорить процесс подготовки документов;
• урегулировать споры между сотрудниками в вопросах оформления документации.

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

• введение;
• структура документов, разделов;
• общие правила оформления;
• язык документации.

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

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

Выделять термины в тексте следует полужирным, цветным шрифтом или курсивом? В подписях к изображениям необходимо прописывать слово «рисунок» или достаточно сокращённого варианта «рис.»? На каком расстоянии от текста должны располагаться таблицы? Ответы на эти и подобные вопросы можно найти в разделе «Общие правила оформления».

Раздел «Язык документации» включает в себя информацию о том, на каком языке (русском, английском, китайском и др.) следует писать документацию, какие термины и профессионализмы допустимо употреблять в документах, какого стиля изложения следует придерживаться. Например, многие организации из этических соображений отказываются от использования слова «инвалид», заменяя его фразой «лицо с ограниченными возможностями». Подобную информацию следует указать в разделе.

Итак, стайлгайд – удачное решение для ускорения процесса разработки документации и приведения её к единому оформлению. Проще один раз составить руководство по стилю, чем постоянно вносить коррективы в документы, составленные разными сотрудниками.