Рисунки, схемы, скриншоты и другие изображения являются неотъемлемой частью любой пользовательской документации. Один скриншот с выносками может дать начинающему пользователю больше информации, чем страница печатного текста. Несмотря на это, многие авторы всячески избегают изображений. Они делают пользовательскую документацию текстовой, ссылаясь на трудоемкость обновления рисунков. В этой статье я расскажу, как поддерживать скриншоты в актуальном состоянии.
Сразу оговорюсь: я не знаю проверенного ПО, которое бы могло автоматизировать обновление скриншотов. Действительно, есть сервисы, например, https://user-docs.com/. Возможно, есть другие веб-приложения или приложения для ПК. Но я не видел ни одного реального отзыва пользователей, не читал документацию на такие приложения и не знаю, как они работают.
За время работы техническим писателем я сформулировал для себя ряд принципов использования скриншотов (рисунков, схем и изображений вообще – далее буду пользоваться термином «скриншоты»). Они позволяют мне активно использовать скриншоты в документации и эффективно поддерживать их в актуальном состоянии.
Основные принципы использования скриншотов
1. Требования к ПО
- ПО для работы со скриншотами должно позволять делать снимки и вставлять выноски на лету.
- Скриншоты должно быть видно в тексте документации.
- Должна быть возможность работы со скриншотами отдельно от текста.
Я использую Fast Stone Capture и/или Impict в связке с Help+Manual и MS Word. Fast Stone Capture и Impict позволяют быстро делать скриншоты, добавлять выноски и обновлять их.
2. Сохранение исходников
Я всегда сохраняю исходники сложных схем и других подобных рисунков (в MS Visio, Balsamic Mockups и др.). Это позволяет быстро отредактировать блок-схему, снимок со множеством выносок, пояснений и т.п. Редактор изображений Impict, поставляемый с Help+Manual, позволяет хранить редактируемые выноски в формате IPP (Impict Project Files).
3. Когда использовать скриншоты
Я обязательно использую скриншоты с выносками при описании нового функционала, так как лучше один раз увидеть, чем сто раз прочитать. В пошаговых инструкциях стараюсь не делать снимков каждого шага. Один снимок с маркерами и выносками – оптимальный вариант. Стараюсь не делать снимки диалоговых окон с запросами для подтверждения команд. Исключение составляют необычные запросы, в которых кроме возможности подтверждения или отмены содержится важная информация или дополнительные варианты действий. Я не делаю снимков кода – вставляю код текстом, чтобы его можно было скопировать и пользоваться. Не вставляю в предложения снимки кнопок – название кнопки, выделенное полужирным шрифтом, работает не хуже.
4. Область скриншота
Хороший скриншот должен содержать описываемый объект и связанный с ним контекст. Контекст можно немного затемнить, объект – выделить. Стараюсь делать затемнения и выделения в едином стиле. Личные данные лучше не размывать – для документации можно создать специальный аккаунт с вымышленными личными данными.
В разделах документации, ориентированных на начинающих пользователей, я использую снимки окон целиком, добавляю маркеры (шаги) и выноски.
Если интерфейс приложения простой, например, похожий на MS Word, я сужаю область скриншота до описываемых элементов.
По возможности ужимаю окна, панели и т.п. до минимального размера, в том числе с использованием графического редактора. На приведенных ниже примерах подъем вкладок панели Keywords позволил сократить высоту скриншота и размер файла примерно в 3 раза.
5. Текст рядом со скриншотом
В расположенный рядом со скриншотом текст я стараюсь включить название окна, формы и т.п. При изменении внешнего вида и/или функционала данного окна / формы это позволяет быстро найти скриншот в тексте и при необходимости обновить.
6. Проверка документации
Я регулярно проверяю актуальность всех скриншотов в проекте. Для решения этой задачи предпочитаю работать со скриншотами отдельно от текста. Help and Manual так работает по умолчанию. В Word есть режим вставки рисунка «Связать с файлом». Я открываю рисунки по очереди и сравниваю их с приложением. Если что-то изменилось, делаю новый снимок и сохраняю поверх старого. В документацию скриншоты подгружаются автоматически. Fast Stone Capture позволяет делать скриншоты и добавлять выноски на лету. Если требуется обновить текст, создаю отдельную задачу по каждому скриншоту. Найти все экземпляры скриншота по имени файла в проекте Help+Manual не проблема.
Что дает мне такая стратегия
Описанная стратегия работы со скриншотами позволяет измерять трудоемкость обновления скриншотов, отталкиваясь не от объема документации, а от количества скриншотов. Обновление одного скриншота занимает порядка одной минуты. Скриншота с выносками - от 3 до 5 минут. Обновление сложных блок-схем занимает больше 5 минут, но их в проекте, как правило, единицы.
Главное, что процесс обновления скриншотов становится прозрачным, понятным и управляемым.
Как я к этому пришел
В течение 7,5 лет я документировал программный комплекс ГОССТРОЙСМЕТА. Так как его основными пользователями были женщины старше 50 лет, глубоко знающие сметное дело и плохо владеющие ПК, заказчиком было принято решение делать подробные скриншоты с выносками и пояснениями.
В последней выпущенной мной в конце 2015 года версии документации было 869 скриншотов. До определенного момента я поддерживал второй комплект скриншотов для Windows XP c автоматическим выводом разных скриншотов в разные сборки документации. Перед сдачей документации я каждый раз проверял актуальность всех скриншотов. На их обновление уходило в среднем 2-3 рабочих дня.
Выводы
Особая трудоемкость обновления скриншотов – это миф, выдуманный лентяями, никогда не имевшими вкуса к труду и не любившими свое дело. Обновлять скриншоты так же трудоемко, как обновлять текстовую документацию. Создавать и обновлять скриншоты – это работа технического писателя. Если вы считаете, что это трудоемко, пересмотрите свою политику использования ПО. Переходите на современные средства разработки документации, в которых работать со скриншотами удобно.
