Приемы эффективной разработки документации к ПО и...
TRANSCRIPT
Не источником единым:эффективные приемы создания
технической документации
Журавлев ДенисООО Индиго Байт
27 ноября 2014
Применимо ко многим, продемонстрировано в …
Dr.Explain - программа для быстрой разработки пользовательской документации к ПО и техническим системам
Инструментарий
Один проект – несколько форматовТехника #1
Генерация из одного проекта-источника документации в различных форматах:
- Традиционный help-файл
- Online-руководство или справочная система
- Печатная документация
Без дополнительных усилий и инструментов
Сложные иллюстрации – составные редактируемые объекты, а не растры
Техника #2
При обновлении аннотированного скриншота, блок-схемы или инфо-графики нет необходимости переделывать всю иллюстрацию полностью
Техника #3
Использование сочетаний клавиш для типовых операций при редактировании может увеличить скорость работы в разы
Hotkeys и сочетания клавиш – оружие профессионалов
Техника #4
Применение именованных текстовых стилей к стандартным элементам документации ускоряет работу и упрощает обновление
Собственные стили – багаж, который не тянет
Техника #5
Если фрагмент будет повторяться в документе более пяти раз, разумно сразу использовать вместо него переменную/макрос/сниппет
Переменные или сниппеты – вместо «копипасты»
Техника #6
Автоматически создаваемые оглавления документа, разделов и подразделов –залог целостной и связанной навигации
Оглавления, составленные вручную?Шутите?
Техника #7
Больше автоматизированного контроля:
- орфография
- связанность
- целостность ссылок
- полнота
- отсутствие дублей
- …
Средства контроля и проверки
Техника #8
Цветовая маркировка статусов готовности элементов
Блокировка от изменений
Использование слов-маркеров (TODO)
Маркировка элементов проекта
Техника #9
Режим командной строки позволяет встроить этап создания документации в общий процесс сборки приложения/системы
Автоматизация компиляций и экспорта
Техника #10
Упрощает:
- Контроль доступа
- Просмотр изменений
- Составление отчетов
- Контроль выполнения задач
История правок – рабочий инструмент менеджера проекта
* Для удаленных Dr.Explain-проектов, хранящихся на платформе tiwri.com
Техника #11
Фактически, создание документации к документации без лишних хлопот
Комментарии к изменениям - не сложно, но важно
* Для удаленных Dr.Explain-проектов, хранящихся на платформе tiwri.com
Техника #12
Альтернатива -хранение проектов в удаленном репозитории
Регулярные бэкапы – залогпсихического здоровья
* Для удаленных Dr.Explain-проектов, хранящихся на платформе tiwri.com
