Главные стандарты документирования

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

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

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

Участники вашей команды теряют время, постоянно объясняя другим, как выполнять работу? Когда в офисе нет того единственного сотрудника, который знает, как решать важное задание, это ставит вас в тупик?

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

Чтобы подобная документация лучше выполняла свою функцию и ее было проще составлять, нужны соответствующие стандарты. И в этом случае опять пригодится шаблон. Например, шаблон статьи с инструкциями Confluence послужит образцом для документирования процессов.

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

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

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

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

• Структурированность. Знать, какую информацию необходимо задокументировать, — это одно. Представить ее в понятном, легко усваиваемом формате — совсем другое. Информация должна быть не просто логически упорядочена; важно также использовать такие элементы, как названия разделов и маркированные списки, которые помогут пользователям ориентироваться в вашей документации.
• Понятность. Чтобы создать понятную, простую для понимания документацию, нужно правильно определить, как сильно следует углубляться в конкретику. Недостаток информации может привести в замешательство, равно как и ее избыток. Также, чтобы документация была понятнее, следует неукоснительно соблюдать правила грамматики, избегать жаргонизмов и употреблять точные формулировки вместо расплывчатых (например, «часто»).
• Единообразие. Следите за единообразием. Это одно из наиболее важных достоинств документации, которое оценят ее пользователи. Например, пользователю проще разобраться с документацией, содержащей практические советы и инструкции, если она составлена так же, как и другие руководства в вашей организации.

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

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

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

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

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

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

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

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