Обзор техник и приёмов для более эффективной работы с пользовательской документацией к программным и техническим системам. Данные подходы возможно использовать в различных программах для работы с документацией — как в системах единого источника, так и в более традиционных инструментах. В качестве практической демонстрации большинство техник разобрано на примере программы Dr.Explain.

1. Не источником единым:
эффективные приемы создания
технической документации
Журавлев Денис
ООО Индиго Байт
27 ноября 2014

2. Применимо ко многим, продемонстрировано в …
Dr.Explain - программа
для быстрой
разработки
пользовательской
документации к ПО и
техническим системам
Инструментарий

3. Техника #1
Один проект – несколько форматов
Генерация из одного
проекта-источника
документации в
различных форматах:
- Традиционный help-файл
- Online-руководство или
справочная система
- Печатная документация
Без дополнительных
усилий и инструментов

4. Техника #2
Сложные иллюстрации – составные
редактируемые объекты, а не растры
При обновлении
аннотированного
скриншота, блок-
схемы или инфо-
графики нет
необходимости
переделывать всю
иллюстрацию
полностью

5. Техника #3
Hotkeys и сочетания клавиш – оружие
профессионалов
Использование
сочетаний клавиш
для типовых
операций при
редактировании
может увеличить
скорость работы в
разы

6. Техника #4
Собственные стили – багаж, который
не тянет
Применение
именованных
текстовых стилей к
стандартным
элементам
документации
ускоряет работу и
упрощает
обновление

7. Техника #5
Переменные или сниппеты – вместо
«копипасты»
Если фрагмент будет
повторяться в
документе более
пяти раз, разумно
сразу использовать
вместо него
переменную/макрос/
сниппет

8. Техника #6
Оглавления, составленные вручную?
Шутите?
Автоматически
создаваемые
оглавления
документа, разделов
и подразделов –
залог целостной и
связанной навигации

9. Техника #7
Средства контроля и проверки
Больше
автоматизированного
контроля:
- орфография
- связанность
- целостность ссылок
- полнота
- отсутствие дублей
- …

10. Техника #8
Маркировка элементов проекта
Цветовая
маркировка статусов
готовности элементов
Блокировка от
изменений
Использование слов-
маркеров (TODO)

11. Техника #9
Автоматизация компиляций и
экспорта
Режим командной
строки позволяет
встроить этап
создания
документации в
общий процесс
сборки
приложения/системы

12. Техника #10
История правок – рабочий
инструмент менеджера проекта
Упрощает:
- Контроль доступа
- Просмотр изменений
- Составление отчетов
- Контроль выполнения
задач
* Для удаленных Dr.Explain-проектов, хранящихся на платформе tiwri.com

13. Техника #11
Комментарии к изменениям - не
сложно, но важно
Фактически, создание
документации к
документации без
лишних хлопот
* Для удаленных Dr.Explain-проектов, хранящихся на платформе tiwri.com

14. Техника #12
Регулярные бэкапы – залог
психического здоровья
Альтернатива -
хранение проектов в
удаленном
репозитории
* Для удаленных Dr.Explain-проектов, хранящихся на платформе tiwri.com

15. Работайте эффективно!
Работайте в удовольствие!
Журавлев Денис
info@drexplain.com
www.drexplain.ru