(4) Техническая документация в IT-проектах. Требования к документационному инструментарию

http://documentat.io/sdo

http://documentat.io/sdo/courses/open-course

Открытый онлайн-курс о технической документации в IT-проектах.

Чат для обсуждений: https://t.me/TechDocIT

Лекция 4. Требования к документационному инструментарию

Видео: https://youtu.be/Sawz84gY4Uk

Transcript

1. www.documentat.io Семëн Факторович sam@documentat.io Техническая документация в IT-проектах
2. • Консалтинг и настройка процессов документирования • Заказная разработка документации • Бесплатный аудит вашей документации Обязательная минутка рекламы www.documentat.io
3. В предыдущей серии
4. Технический документ — это… проектный артефакт технической документации, связывающий двух определенных стейкхолдеров и являющийся обособленной единицей в терминах •целеполагания, •контроля качества, •и публикации.
5. Технический документ — проектный артефакт технической документации, связывающий двух определенных стейкхолдеров и являющийся обособленной единицей в терминах •целеполагания, •контроля качества, •и публикации.
6. Артефакт + процесс вокруг него = жизненный цикл
8. Документационный инструментарий
9. • Разработка Документационный инструментарий
10. • Разработка • Ревью Документационный инструментарий
11. • Разработка • Ревью • Хранение Документационный инструментарий
12. • Разработка • Ревью • Хранение • Публикация Документационный инструментарий
13. • Разработка • Ревью • Хранение • Публикация Документационный инструментарий
14. Инструментарий хранения
17. — Где последняя спека? — Переписка «RE: RE: FWD: Последняя версия с правками» от 12 февраля 2020
19. — Где последняя спека? — //share.local/Project/Specs/SRS.docx
20. А как же история ревизий?
23. — Где последняя спека? — Наша корпоративная общая папка в Dropbox, а дальше /Project/Specs/Mega_Project_SRS.docx
25. Требования к инструментарию хранения
26. • Однозначная локация документа (файл в репозитории, URL…) Требования к инструментарию хранения
27. • Однозначная локация документа (файл в репозитории, URL…) • Автоматически поддерживаемая история ревизий Требования к инструментарию хранения
28. • Однозначная локация документа (файл в репозитории, URL…) • Автоматически поддерживаемая история ревизий • Обнаруживаемость (discoverability): возможность увидеть весь список документов Требования к инструментарию хранения
29. Инструментарий ревью
30. Инструментарий ревью
31. • Комментарии (желательно, к фрагменту текста, а не ко всему тексту) • Workflow комментариев: закрытие, переоткрытие, ветки дискуссий… • Точечное отслеживание изменений: что же поменялось с предыдущей ревизии? Инструментарий ревью
32. • Комментарии (желательно, к фрагменту текста, а не ко всему тексту) • Workflow комментариев: закрытие, переоткрытие, ветки дискуссий… • Точечное отслеживание изменений: что же поменялось с предыдущей ревизии? Инструментарий ревью Без этого комментарии и изменения придется передавать по отдельному каналу коммуникации
33. • Комментарии (желательно, к фрагменту текста, а не ко всему тексту) • Workflow комментариев: закрытие, переоткрытие, ветки дискуссий… • Точечное отслеживание изменений: что же поменялось с предыдущей ревизии? Инструментарий ревью Без этого комментарии и изменения придется передавать по отдельному каналу коммуникации
34. • Однозначная локация документа (файл в репозитории, URL…) • Автоматически поддерживаемая история ревизий И снова хранение
35. • Однозначная локация документа (файл в репозитории, URL…) • Автоматически поддерживаемая история ревизий И снова хранение Все это очень сильно облегчает ревью
36. • Однозначная локация документа (файл в репозитории, URL…) • Автоматически поддерживаемая история ревизий И снова хранение Все это очень сильно облегчает ревью
37. Инструментарий ревью не создаст вам процессы ревью
38. Cовместное одновременное редактирование не нужно
39. Подходящие инструменты на данный момент
40. • Google Docs Подходящие инструменты на данный момент
41. • Google Docs • Confluence Подходящие инструменты на данный момент
42. • Google Docs • Confluence • MS Word + Office365 + OneDrive Подходящие инструменты на данный момент
43. • Google Docs • Confluence • MS Word + Office365 + OneDrive Подходящие инструменты на данный момент + Процессы ревью и регламенты хранения
44. • Конвертация во что-то удобочитаемое • PDF • HTML • Красивый DOCX Инструменты публикации
45. Инструменты разработки
46. • Переиспользование контента Инструменты разработки
47. • Переиспользование контента • Блоки текста Инструменты разработки
48. • Переиспользование контента • Блоки текста • Текстовые переменные Инструменты разработки
49. • Переиспользование контента • Блоки текста • Текстовые переменные • Строгое соответствие визуальным шаблонам (ГОСТ, корпоративная айдентика) Инструменты разработки
50. • Переиспользование контента • Блоки текста • Текстовые переменные • Строгое соответствие визуальным шаблонам (ГОСТ, корпоративная айдентика) • Скорость создания контента Инструменты разработки
51. • Переиспользование контента • Блоки текста • Текстовые переменные • Строгое соответствие визуальным шаблонам (ГОСТ, корпоративная айдентика) • Скорость создания контента • Удобный WYSIWYG Инструменты разработки
52. • Переиспользование контента • Блоки текста • Текстовые переменные • Строгое соответствие визуальным шаблонам (ГОСТ, корпоративная айдентика) • Скорость создания контента • Удобный WYSIWYG • Простая разметка Инструменты разработки
53. • Author-it • MadCap Flare • Help&Manual Help Authoring Tools, HATs
54. • В первую очередь инструментарий разработки • Процессы ревью, подходы к хранению и пр. вторичны Help Authoring Tools, HATs
55. • В меньшей степени применимы для «быстрых» документов • Барьер входа в создание документации высок Help Authoring Tools, HATs
56. Специфические желания
57. • Сравнение произвольных ревизий Специфические желания
58. • Сравнение произвольных ревизий • Blame: кто автор этой строчки? Специфические желания
59. • Сравнение произвольных ревизий • Blame: кто автор этой строчки? • Синхронизация изменений в коде и изменений в документации Специфические желания
60. • Сравнение произвольных ревизий • Blame: кто автор этой строчки? • Синхронизация изменений в коде и изменений в документации • Автоматизированная публикация Специфические желания
61. • Давайте относиться к документации как к коду! • Хранить ее в plain text в репозитории Docs as code
62. • Легковесные языки разметки • Markdown • Asciidoc • RST Docs as code
63. • Экосистема инструментария конвертации и публикации • PDF • Многостраничный HTML • DOCX Docs as code
64. • Большинство инструментов публикации • бесплатны • открыты • встраиваются в CI/CD-конвейеры Docs as code
65. • Все преимущества Git • diff • blame • merge Docs as code
66. Модели ветвления, Git workflows
67. • Давайте переиспользуем инструментарий для кода! • Pull/merge requests в вашем любимом GitHub/ GitLab/Bitbucket Ревью в docs as code?
68. Docs as code, плюсы
69. • Невероятная гибкость инструментария Docs as code, плюсы
70. • Невероятная гибкость инструментария • Синхронизация изменений в коде и в документации Docs as code, плюсы
71. • Невероятная гибкость инструментария • Синхронизация изменений в коде и в документации • Автоматизация публикации «из коробки» Docs as code, плюсы
72. Docs as code, минусы
73. • Ревью не всегда удобно Docs as code, минусы
74. • Ревью не всегда удобно • Высокая стоимость первичной настройки Docs as code, минусы
75. • Ревью не всегда удобно • Высокая стоимость первичной настройки • Все еще высокий барьер создания документации Docs as code, минусы
76. • Ревью не всегда удобно • Высокая стоимость первичной настройки • Все еще высокий барьер создания документации • Иногда очень не хватает WYSIWYG:( Docs as code, минусы
77. Подытожим
78. • Ваш инструментарий покрывает Подытожим
79. • Ваш инструментарий покрывает • Разработку документации Подытожим
80. • Ваш инструментарий покрывает • Разработку документации • Ее ревью Подытожим
81. • Ваш инструментарий покрывает • Разработку документации • Ее ревью • Ее хранение Подытожим
82. • Ваш инструментарий покрывает • Разработку документации • Ее ревью • Ее хранение • Ее публикацию Подытожим
83. • Ваш инструментарий покрывает • Разработку документации • Ее ревью • Ее хранение • Ее публикацию • Но он не создаст вам процессы Подытожим
84. Подытожим
85. • Скорее всего, вы будете смотреть в сторону чего-то одного Подытожим
86. • Скорее всего, вы будете смотреть в сторону чего-то одного • Коллаборативный WYSIWYG (Google Docs, Office365, Confluence…) Подытожим
87. • Скорее всего, вы будете смотреть в сторону чего-то одного • Коллаборативный WYSIWYG (Google Docs, Office365, Confluence…) • Help Authoring Tools Подытожим
88. • Скорее всего, вы будете смотреть в сторону чего-то одного • Коллаборативный WYSIWYG (Google Docs, Office365, Confluence…) • Help Authoring Tools • Docs as code Подытожим
89. • Выбор инструментального стека – не навсегда • Миграция с DOCX на docs as code • Миграция с DOCX на Confluence Подытожим
90. • Выбор инструментального стека – не навсегда • Миграция с DOCX на docs as code • Миграция с DOCX на Confluence Подытожим www.documentat.io
91. • DITA и DocBook, стандарты и экосистемы инструментария разработки документации • Инструментарий управления переводами О чем еще не поговорили
92. • DITA/DocBook, стандарт и экосистема инструментария • Help Authoring Tools на конкретных примерах • Docs as code как философия • Docs as code на конкретных примерах О чем обязательно поговорим
93. DocOps как расширение идеи docs as code Николай Волынкин (Plesk) В следующей серии
94. • Консалтинг и настройка процессов документирования • Заказная разработка документации • Бесплатный аудит вашей документации Обязательная минутка рекламы www.documentat.io