Создание более качественной документации

Вы только что запустили проект и теперь должны разработать документацию (подсказка: $#*&^!%).

На первый взгляд это может показаться непростой задачей, но мы готовы помочь! Ниже вы найдете документацию по документации [(wink)] — пошаговое руководство с профессиональными советами, которые помогут вам в процессе работы.Давайте приступим!


Почему это должно меня интересовать?

Если говорить простыми словами, то документация помогает людям делать свою работу. Но, подобно многим удивительным вещам, у нее есть и другие преимущества. Документация помогает пользователям и командам:

Затрачивать меньше умственных усилий

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

Обеспечить единообразие

Обеспечить последовательную работу читателей с имеющейся информацией, процессами и планами.

Минимизировать рабочую нагрузку

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

Улучшить имидж компании

Продемонстрировать отношение к внешним клиентам и сотрудникам компании, предложив им поддержку и помощь.

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

Что такое документация?

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

Документация должна служить двум основным целям:

1. Информировать пользователей.

2. Помогать пользователям успешно выполнить задачу.

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

Типы документации

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



Внутренняя документация
team-documentation-illustration

Документация для команд

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

reference-documentation-illustration

Справочная документация

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

project-documentation-illustration

Проектная документация

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



ВНЕШНЯЯ ДОКУМЕНТАЦИЯ
system-documentation-illustration

Системная документация

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

end-user-documentation-illustration

Пользовательская документация

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

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

Создание документации

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

1. Исследование

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

2. Начало работы

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

3. Описание подробностей

Составьте план и сделайте черновой вариант документа. Выберите стиль и тональность с учетом аудитории (текст должен легко восприниматься!). Используйте последовательные и лаконичные формулировки, а также четко излагайте важные детали.

4. Форматирование

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

5. Рецензирование

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

6. Публикация

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

Ценная информация

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

Стремитесь к краткости

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

Помните о важности визуальных элементов

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

Определите свою аудиторию

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

Приступайте к работе без промедления

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

Подробнее