5 способов улучшить пользовательскую документацию с помощью блок-схем и диаграмм

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

Типичному руководству пользователя не хватает графики

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

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

#1: Превратите пошаговые инструкции в блок-схемы

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

#2: Никогда не представляйте структуру в виде списка

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

Пример:

#3: Используйте UML-диаграммы для документирования классов

Так, UML-диаграммы хороши для представления иерархии и структуры классов объектно-ориентированных языков. Такие диаграммы не только компактнее и легче для восприятия, они также лучше отображают взаимосвязи и зависимости между классами. А это очень важно при документировании библиотек, программных компонентов и пакетов.

Вот пример диаграммы класса:

Бросив быстрый взгляд на диаграмму, можно сразу увидеть основные объекты системы (Visitor, Admin, Movie, Registered User, Book Ticket, Payment), все главные свойства каждого объекта (например, идентификатор, имя, телефон и адрес зарегистрированного пользователя), возможные действия с объектом и его связь с остальными объектами.

Альтернативой было бы представление классов в виде исходного кода, что очевидно менее наглядно.

#4: Блок-схемы идеальны для описания технологических процессов

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

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

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

#5: Показывайте ER-модели правильно (читай: визуально)

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

Заключение

Создать готовое к публикации руководство по использованию продукта непросто. Однако, вооружившись правильными инструментами для создания пользовательской документации такими, как Dr.Explain (http://www.drexplain.ru), вы сможете создать понятную, доступную и наглядную документацию, которая действительно сможет помочь вашим пользователям в освоении вашего продукта и в работе с ним.