Давайте представим ситуацию, что вы завершили работу над важным этапом проекта. Вам удалось достичь всех поставленных целей и оправить в продакшн замечательный продукт. Есть только одна проблема: никто, кроме вас, не знает, как им пользоваться. А вы как раз собираетесь уехать в шестимесячный кругосветный отпуск.
Вы начинаете всё записывать. Однако не помните, как именно решали те или иные проблемы четыре месяца назад. Многое из написанного, рассчитано на то, что читатель знает столько же, сколько и вы. Но вы даже не помните, как связаны между собой некоторые части или как именно они должны работать вместе.
Описанная ситуация встречается достаточно часто. Документация, особенно техническая, нередко пишется, когда до сдачи проекта остаётся немного времени, а большая часть работы уже выполнена. Это приводит к тому, что документация становится непонятной и трудной для чтения.
Из этой статьи вы узнаете, как подходить к составлению технической документации, когда следует это делать, что нужно учитывать при её написании и почему документация так важна.
БЕСПЛАТНО СКАЧАТЬ КНИГИ в телеграм канале "Библиотека тестировщика"
Что такое техническая документация
Прежде чем говорить о методах создания документации, времени начала этого процесса и т. д., необходимо понять, о чём идёт речь. Эта статья рассматривает документацию как письменное описание того, над каким продуктом ведётся работа, а также инструкциями по его использованию. Это определение применимо и к технической документации.
Техническая документация рассматривается на примере документирования программного обеспечения, однако многие идеи являются универсальными. Они могут быть применены к руководству пользователя или любому техническому документу.
Важность документации
Хорошая документация действует как руководство, описывающее продукт, для читателей. Она помогает понять, что за продукт создан, почему он важен и как он работает. Необходимо, чтобы документация направляла читателя, отвечала на его вопросы и описывала важные аспекты продукта.
Без хорошей документации читатель, скорее всего, не сможет использовать продукт в полной мере. Некоторые функциональные возможности и детали могут быть упущены. С увеличением сложности продукта качество документации становится более принципиальным.
Когда нужно писать документацию
Многие считаю, что документация должна быть создана после завершения проекта — у вас есть задача или цель, вы упорно работаете над её достижением, и только после этого приступаете к написанию документации.
Однако это не самый лучший момент, чтобы начать работу над документацией. Некоторые захотят поспорить с этим тезисом. Так как только в конце работы у команды появляется целостная картина законченного проекта.
Но это не совсем верно. И вот почему. К моменту завершения работы некоторые детали, которые повлияли на достижение поставленных целей, начнут забываться, что приведёт к написанию слабой документации. Этот эффект ещё больше проявляется в случае большого или сложного проекта.
Вместо этого нужно вести документацию по ходу работы над проектом. Стоит всегда держать документацию под рукой, чтобы в любой момент внести какие-то дополнения или изменения. А время в конце проекта можно использовать для её редактирования, чтобы сделать документацию ещё качественней.
Разница между «хорошей» и «плохой» документацией
Почти каждый человек сталкивался с плохо написанной инструкцией, в которой сложно понять смысл текста, отсутствуют важные детали и т. д. А попытки разобраться в этой инструкции заканчиваются поиском другого ответа в Google.
Хорошая документация понятна читателю даже без соответствующего опыта. Она очевидна, содержит чёткие и воспроизводимые шаги, приводит к выполнению поставленной задачи.
Как написать хорошую документацию
Для написания хорошей документации можно придерживаться следующих советов.
Писать для целевой аудитории
Очень важно знать аудиторию, это позволит написать документацию в соответствии с уровнем аудитории, на понятном ей языке. Это может быть непросто, так как любая ошибка в оценке аудитории приведёт к сложностям в использовании документации пользователями.
Например, нужно создать документацию для набора средств автоматизации тестирования веб-сайта. Если предполагать, что аудитория знакома с процессом автоматизации, можно начать инструкцию со слов «Шаг 1. Запустите веб-сайт локально». Предположение, что читатель знает, как «запустить сайт локально», — исключает тех, кто не знаком с этой темой. Вся информация, которая последует дальше, может оказаться для них бесполезной.
С другой стороны, можно предположить, что аудитория ничего не знает. Однако такой подход может оттолкнуть более опытных пользователей.
Оптимальный вариант находится где-то посередине. Исходя из приведённого выше примера, стоит подумать о том, кто будет выполнять автоматизированный тестовый набор — скорее всего, это будут опытные тестировщики и разработчики. В таком случае писать документацию следует на понятном для них языке, например, используя специальные термины.
Использовать модульную документацию
Вернёмся к примеру с запуском веб-сайта. Возможно это не такое плохое начало инструкции. Во всяком случае для тех, кто знаком с данным продуктом, не потребуется больше информации. Но что делать тем, кому нужно более подробное объяснение?
Написать больше документации!
Например, следует проверить, написана ли документация на тему «как запустить веб-сайта локально». Если такая документация существует, нужно убедиться, что она по-прежнему актуальна. И просто добавить ссылку на неё. В случае, когда такой инструкции нет, нужно написать новую документацию по этой теме.
Такой подход сделает документацию более практичной. Она подойдёт как новичку, так и более опытному пользователю.
Рецензирование
Последний шаг перед завершением написания документации — это провести её оценку. Идеально, если оценку проведёт ваш коллега, который сможет подтвердить корректность документации. Также, если возможно, стоит отдать документацию на рецензирование потенциальному пользователю.
Хорошим примером является документация для нового сотрудника. Подобная документация обычно пишется для людей, которые только пришли в новый проект или организацию и их необходимо ввести в курс дела. Сотрудники, которые пишут такую документацию, не всегда помнят, что было важным для новичка. Таким образом, легко упустить полезные детали.
Для уверенности в том, что документация по введению в должность сотрудника является полной и точной, её должен просмотреть тот, кто сам проходит через этот процесс. Рекомендуется находиться рядом с новым сотрудником, и наблюдать за тем, как он использует документацию. Следует отметить все трудности и вопросы, которые возникли у сотрудника. Это позволит обновить документацию и сделать её более полезной. Этот процесс можно продолжать до тех пор, пока документация не станет исчерпывающей и не потребует дополнительной помощи.
Перевод статьи «How to Write Technical Documentation That People Will Actually Read and Use».