Как ваши разработчики могут улучшить документацию компании

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

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

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

• Как использовать программное обеспечение
• Использование оборудования
• Любой рабочий процесс
• Общие передовые методы
• Ввод в должность сотрудников
• Кадровая работа и подбор персонала

Разработка политики документирования

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

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

Разработав эти правила, убедитесь, что вся документация следует им в точности.

Используйте активный голос

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

Простой пример активного и пассивного голоса выглядит следующим образом:

• Активный залог – Боб пробежал марафон.
• Пассивный залог – Марафон был пройден Бобом

Когда вы используете активный залог, субъект выполняет действие (Боб пробежал марафон). При использовании пассивного залога субъект выполняет действие (Боб пробежал марафон).

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

Поощряйте использование броских заголовков

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

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

Оставьте в прошлом "жужжащие" слова и аббревиатуры

Применяя броские заголовки, старайтесь избегать использования сложных слов. Это особенно важно в сфера технологий, поскольку не все понимают все эти "жужжащие" слова и аббревиатуры.

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

Добавление визуальных материалов

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

Создавайте и используйте шаблоны

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

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

Заключение

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