Блог технического писателя Ильи Жукова

Как поддерживать скриншоты в актуальном состоянии

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

 

Сразу оговорюсь: я не знаю проверенного ПО, которое бы могло автоматизировать обновление скриншотов. Действительно, есть сервисы, например, 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 рабочих дня.

 

Выводы

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

 

Добавить комментарий

Последние статьи

Подключение таблицы стилей к проекту Hel…

При работе с форматами, основанными на HTML, для оформления контента в документах можно использовать каскадные таблицы стилей, cascading style sheets или CSS. Данная т...

Читать полностью...

Формулы в HTML Help (CHM)

Я по образованию филолог. Специализируюсь на разработке пользовательской документации на английском и русском языках. С формулами в документации сталкиваюсь редко и по...

Читать полностью...

Импорт документов MS Word в Help+Manual…

Часто технический писатель получает исходные данные от аналитиков, разработчиков, тестировщиков, маркетологов и других специалистов в форматах DOC, DOCX и RTF (реже, и...

Читать полностью...

Поиск в WebHelp находит удаленные раздел…

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

Читать полностью...

Контекстная справка в приложениях Window…

Понятие контекстной или контекстно-зависимой справки (от англ. context-sensitive help) появилось в 1987 году с выходом формата WinHelp. Изначально контекстная справка ...

Читать полностью...

Книга «Разработка технической документац…

Уважаемые коллеги! Если вам нужно быстро освоить разработку документации по ГОСТ, рекомендую обратить внимание на книгу В.А. Глаголева «Разработка технической документ...

Читать полностью...

Перевод выходных документов в Help and M…

Выбрав русский язык и русскую кодировку в настройках проекта Help and Manual, многие авторы после первой сборки удивляются, увидев в выходных документах английские сло...

Читать полностью...

Размер и расположение окна CHM при перво…

Разработчик справки в формате CHM может задать размер и расположение окна, которые будут использоваться при первом запуске CHM-файла. После того, как пользователь пере...

Читать полностью...

Рваные края скриншотов в Help and Manual…

Многие платные редакторы скриншотов, например, SnagIt, FastStone Capture и др., умеют создавать эффект рваных краев. В сети Интернет можно найти множество видеоуроков ...

Читать полностью...
новое в Help and Manual 9

Новое в Help and Manual 9

23 ноября 2022 года компания EC Software к 25-летнему юбилею выпустила 9-ю версию программного комплекса Help and Manual (выходит c 1997 года). Комплект шаблонов Premi...

Читать полностью...

Создание CHM-справки в бесплатной програ…

KEL CHM Creator — это «новая» хорошо забытая программа, выпущенная в 2012 году, предназначенная для создания и декомпиляции CHM-файлов. Программа не требовательна к ре...

Читать полностью...

KEL CHM Creator — бесплатная программа д…

Если вам нужно создать CHM-файл, и вы больше не хотите пользоваться глючной программой HTML Help Workshop, тогда KEL CHM Creator — это ваш вариант. Программа позволяет...

Читать полностью...
ключевые слова

Ключевые слова в Help+Manual…

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

Читать полностью...

HTML Help Workshop – бесплатная программ…

В 1997 году Microsoft выпустила новый формат справки, HTML Help (CHM), а также бесплатную программу для создания и редактирования справки в этом формате — HTML Help Wo...

Читать полностью...

HelpNDoc — бесплатная альтернатива Help+…

Еще одной альтернативой RoboHelp и Help&Manual является программа HelpNDoc от французского разработчика, компании IBE Software. Это практически полный аналог HelpS...

Читать полностью...

HelpSmith — достойная альтернатива Help+…

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

Читать полностью...

Все о справке и документации для пользователей!

Следить за новыми статьями:

© Илья Жуков, 2019-2024. Охраняется законом об авторском праве.