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
