День 1761. #Docs
Пишем Документацию, Которую Будут Читать и Использовать
Вы завершили работу и выпустили классный продукт. Но никто, кроме вас, не знает, как им пользоваться. Вы начинаете это описывать… но не помните, как решили ту проблему полгода назад. Многое из того, что вы пишете, предполагает, что читатель знает столько же, сколько вы. И вы даже не помните, как некоторые детали соединены или как должны работать вместе. Это очень распространённый сценарий. Документация часто пишется после того, как всё сделано, и с учётом времени до дедлайна. Мы забываем важные шаги и предполагаем, что у читателей есть опыт и знания. Это делает документацию трудной для чтения и разочаровывает читателей.
Что это?
Мы будем рассматривать документацию как письменное описание всего, над чем вы работали, с инструкциями по использованию готового продукта.
Почему это важно?
Хорошая документация будет служить для читателя путеводителем по продукту, поможет понять, что это, зачем и как работает. Без хорошей документации люди, скорее всего, не смогут полноценно (или вообще) использовать продукт. По мере увеличения сложности продукта качество документации становится всё более важным.
Когда писать?
Часто её пишут в конце. Но это, наверное, худшее время. К тому времени, вероятно, что вы уже начнёте забывать некоторые детали. Документируйте в процессе, шаг за шагом. Держите документацию открытой и близко, чтобы записывать все новые идеи. В конце используйте оставшееся время для редактирования документации.
Как написать хорошую документацию?
Хорошая документация не разочаровывает отсутствием важных шагов, не предполагает наличия опыта, читается легко, содержит чёткие и воспроизводимые шаги и приводит к выполнению нужной задачи.
1. Пишите для своей аудитории
Переоценка или недооценка аудитории, скорее всего, затруднит использование документации для ваших реальных читателей. Предположения о знаниях людей могут оказаться исключающими, если вы не будете осторожны.
Например, вы документируете пакет для тестирования сайта. Если вы предполагаете, что ваша аудитория знает систему, можно начать с «Шаг 1. Запустите веб-сайт локально». Это предположение исключает из аудитории любого, кто не знает, как это сделать. Остальное написанное может быть для него бесполезным.
Другая крайность — допущение, что аудитория ничего не знает. Если это опытные тестировщики, а документация читается так, будто написана для нетехнических людей, читатель может почувствовать, что вы разговариваете с ним свысока, заскучать и бросить чтение. Важен поиск золотой середины.
Пакет тестирования скорее всего используют тестировщики и разработчики. Если он хорош, им могут пользоваться долгие годы. Т.е. у кого-то может быть опыт, а кому-то нужно будет повышение квалификации. Как учесть и тех, и других?
2. Используйте модульную документацию
Возвращаясь к «Шаг 1. Запустите веб-сайт локально». Опытным читателям больше объяснять не надо. А для новичков… напишите больше документации! Точнее, посмотрите, существует ли уже документация для этого. Если да, и она актуальна, оставьте ссылку на неё. Если нет, напишите новую страницу документации об этом.
Модульность документации позволит обеим аудиториям продолжить работу на своём уровне. Экспертам - пройти этот шаг быстро, новичкам - копнуть глубже и получить новый опыт.
3. Пусть её проверят
В идеале проверку должен выполнять коллега, который знает систему, а также кто-то из потенциальной аудитории. Прекрасным примером является документация по онбордингу (вводная документация, позволяющая новичкам в компании быстро освоиться). Обычно её авторы не всегда помнят, что было необходимо и важно для новичка. Легко делать предположения и забыть важные детали. Поэтому её должен проверить тот, кто реально проходит этот процесс. Сядьте с ним и наблюдайте, как он использует документацию, какие трудности возникают. Добавляйте недостающие шаги или упущенные детали, пока документация не станет пригодной для использования без помощи.
Источник
Пишем Документацию, Которую Будут Читать и Использовать
Вы завершили работу и выпустили классный продукт. Но никто, кроме вас, не знает, как им пользоваться. Вы начинаете это описывать… но не помните, как решили ту проблему полгода назад. Многое из того, что вы пишете, предполагает, что читатель знает столько же, сколько вы. И вы даже не помните, как некоторые детали соединены или как должны работать вместе. Это очень распространённый сценарий. Документация часто пишется после того, как всё сделано, и с учётом времени до дедлайна. Мы забываем важные шаги и предполагаем, что у читателей есть опыт и знания. Это делает документацию трудной для чтения и разочаровывает читателей.
Что это?
Мы будем рассматривать документацию как письменное описание всего, над чем вы работали, с инструкциями по использованию готового продукта.
Почему это важно?
Хорошая документация будет служить для читателя путеводителем по продукту, поможет понять, что это, зачем и как работает. Без хорошей документации люди, скорее всего, не смогут полноценно (или вообще) использовать продукт. По мере увеличения сложности продукта качество документации становится всё более важным.
Когда писать?
Часто её пишут в конце. Но это, наверное, худшее время. К тому времени, вероятно, что вы уже начнёте забывать некоторые детали. Документируйте в процессе, шаг за шагом. Держите документацию открытой и близко, чтобы записывать все новые идеи. В конце используйте оставшееся время для редактирования документации.
Как написать хорошую документацию?
Хорошая документация не разочаровывает отсутствием важных шагов, не предполагает наличия опыта, читается легко, содержит чёткие и воспроизводимые шаги и приводит к выполнению нужной задачи.
1. Пишите для своей аудитории
Переоценка или недооценка аудитории, скорее всего, затруднит использование документации для ваших реальных читателей. Предположения о знаниях людей могут оказаться исключающими, если вы не будете осторожны.
Например, вы документируете пакет для тестирования сайта. Если вы предполагаете, что ваша аудитория знает систему, можно начать с «Шаг 1. Запустите веб-сайт локально». Это предположение исключает из аудитории любого, кто не знает, как это сделать. Остальное написанное может быть для него бесполезным.
Другая крайность — допущение, что аудитория ничего не знает. Если это опытные тестировщики, а документация читается так, будто написана для нетехнических людей, читатель может почувствовать, что вы разговариваете с ним свысока, заскучать и бросить чтение. Важен поиск золотой середины.
Пакет тестирования скорее всего используют тестировщики и разработчики. Если он хорош, им могут пользоваться долгие годы. Т.е. у кого-то может быть опыт, а кому-то нужно будет повышение квалификации. Как учесть и тех, и других?
2. Используйте модульную документацию
Возвращаясь к «Шаг 1. Запустите веб-сайт локально». Опытным читателям больше объяснять не надо. А для новичков… напишите больше документации! Точнее, посмотрите, существует ли уже документация для этого. Если да, и она актуальна, оставьте ссылку на неё. Если нет, напишите новую страницу документации об этом.
Модульность документации позволит обеим аудиториям продолжить работу на своём уровне. Экспертам - пройти этот шаг быстро, новичкам - копнуть глубже и получить новый опыт.
3. Пусть её проверят
В идеале проверку должен выполнять коллега, который знает систему, а также кто-то из потенциальной аудитории. Прекрасным примером является документация по онбордингу (вводная документация, позволяющая новичкам в компании быстро освоиться). Обычно её авторы не всегда помнят, что было необходимо и важно для новичка. Легко делать предположения и забыть важные детали. Поэтому её должен проверить тот, кто реально проходит этот процесс. Сядьте с ним и наблюдайте, как он использует документацию, какие трудности возникают. Добавляйте недостающие шаги или упущенные детали, пока документация не станет пригодной для использования без помощи.
Источник
👍7👎2