(#2) Техническая документация в IT-проектах. Типичные проблемы с документацией

http://documentat.io/sdo

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

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

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

Лекция 2. Документация — продукт или процесс? Что с документацией не так? Как это поправить?

Видео: https://www.youtube.com/watch?v=BG5yBiyZTRc

Transcript

1. www.documentat.io Семëн Факторович sam@documentat.io Техническая документация в IT-проектах
2. • Консалтинг и настройка процессов документирования • Заказная разработка документации • Бесплатный аудит вашей документации Обязательная минутка рекламы www.documentat.io
3. В предыдущей серии
5. Спецификация требований Техзадание Техзадание Справочник API Архитектура решения Руководство пользователя Troubleshooting guide
6. • Документация — способ реализации канала коммуникации между парой стейкхолдеров • Документация нужна тогда, когда другие способы реализации этого канала более дороги или рискованны • Если документация реализует коммуникацию не очень эффективно, то стейкхолдеры перейдут к другим вариантам — например, устным В предыдущей серии
7. • Типичные проблемы с документацией и откуда они растут • Техническая документация — процесс или артефакт? Да! О чем будем говорить сегодня
8. Типичные проблемы с документацией
9. • Ее нет Типичные проблемы с документацией
10. • Ее нет • Есть, но никто не читает Типичные проблемы с документацией
11. • Ее нет • Есть, но никто не читает • Читают, но грустят при этом (плохо написана, тяжело читается…) Типичные проблемы с документацией
12. • Ее нет • Есть, но никто не читает • Читают, но грустят при этом (плохо написана, тяжело читается…) • Читают, но все равно приходят с вопросами Типичные проблемы с документацией
13. • Ее нет • Есть, но никто не читает • Читают, но грустят при этом (плохо написана, тяжело читается…) • Читают, но все равно приходят с вопросами • Неполна, содержит не всю необходимую информацию Типичные проблемы с документацией
14. • Ее нет • Есть, но никто не читает • Читают, но грустят при этом (плохо написана, тяжело читается…) • Читают, но все равно приходят с вопросами • Неполна, содержит не всю необходимую информацию • Устаревшая или содержит ошибки Типичные проблемы с документацией
15. • Ее нет • Есть, но никто не читает • Читают, но грустят при этом (плохо написана, тяжело читается…) • Читают, но все равно приходят с вопросами • Неполна, содержит не всю необходимую информацию • Устаревшая или содержит ошибки Типичные проблемы с документацией
16. Документации нет
17. • Все понимают, что она нужна, но никто ее не пишет Документации нет
18. • Все понимают, что она нужна, но никто ее не пишет • Никто не ставит задачу на ее написание Документации нет
19. • Все понимают, что она нужна, но никто ее не пишет • Никто не ставит задачу на ее написание Документации нет
20. • Все понимают, что она нужна, но никто ее не пишет • Никто не ставит задачу на ее написание • Никто не понимает, зачем она нужна (и, соответственно, не пишут) Документации нет
21. Иногда документация действительно не нужна
22. Иногда документация действительно не нужна
23. Иногда документация действительно не нужна
24. • Другие каналы коммуникации (realtime, push) дешевле, чем документация Иногда документация действительно не нужна
25. • Другие каналы коммуникации (realtime, push) дешевле, чем документация Иногда документация действительно не нужна
26. • Другие каналы коммуникации (realtime, push) дешевле, чем документация • Этих двух стейкхолдеров не нужно связывать — канал коммуникации между ними не важен для бизнеса Иногда документация действительно не нужна
27. Иногда документация действительно не нужна
28. • «Онбординг новых сотрудников мы проводим устно» Иногда документация действительно не нужна
29. • «Онбординг новых сотрудников мы проводим устно» Иногда документация действительно не нужна
30. • «Онбординг новых сотрудников мы проводим устно» • «Мы не документируем схему БД, потому что ее можно построить в один клик» Иногда документация действительно не нужна
31. • «Онбординг новых сотрудников мы проводим устно» • «Мы не документируем схему БД, потому что ее можно построить в один клик» Иногда документация действительно не нужна
32. • «Онбординг новых сотрудников мы проводим устно» • «Мы не документируем схему БД, потому что ее можно построить в один клик» • «Наш продукт достаточно прост, ему не нужна пользовательская документация» Иногда документация действительно не нужна
33. Аудит существующей документации
34. Аудит существующей документации
35. • Действительно ли каждый ваш документационный артефакт связывает пару стейкхолдеров? Аудит существующей документации
36. • Действительно ли каждый ваш документационный артефакт связывает пару стейкхолдеров? Аудит существующей документации
37. • Действительно ли каждый ваш документационный артефакт связывает пару стейкхолдеров? • Действительно ли этим двум стейкхолдерам нужна именно документация, а не устное общение? Аудит существующей документации
38. Документацию никто не пишет
39. • Архитектура и дизайн-решения новых фич не документируются (или документируются, но не всегда) Документацию никто не пишет
40. • Архитектура и дизайн-решения новых фич не документируются (или документируются, но не всегда) Документацию никто не пишет
41. • Архитектура и дизайн-решения новых фич не документируются (или документируются, но не всегда) • Изменения в требованиях от заказчика не фиксируются в спецификации требований Документацию никто не пишет
42. • Архитектура и дизайн-решения новых фич не документируются (или документируются, но не всегда) • Изменения в требованиях от заказчика не фиксируются в спецификации требований Документацию никто не пишет
43. • Архитектура и дизайн-решения новых фич не документируются (или документируются, но не всегда) • Изменения в требованиях от заказчика не фиксируются в спецификации требований • Руководство пользователя безнадежно отстало от текущего состояния продукта Документацию никто не пишет
44. В параллельной вселенной
45. • «Мы пофиксали баг, но забыли выкатить этот фикс на прод» В параллельной вселенной
46. • «Мы пофиксали баг, но забыли выкатить этот фикс на прод» В параллельной вселенной
47. • «Мы пофиксали баг, но забыли выкатить этот фикс на прод» • «Новые фичи почему-то не тестируются» В параллельной вселенной
48. • «Мы пофиксали баг, но забыли выкатить этот фикс на прод» • «Новые фичи почему-то не тестируются» В параллельной вселенной
49. • «Мы пофиксали баг, но забыли выкатить этот фикс на прод» • «Новые фичи почему-то не тестируются» • «Иногда мы не забываем делать code review, но чаще всего все-таки забываем» В параллельной вселенной
50. Принципиальные активности разработки (code review, тестирование, деплой) обернуты в процессы В нашей вселенной
51. Документация не заводится сама
52. • «Деградация» коммуникации от документации до устного общения происходит самостоятельно Документация не заводится сама
53. • «Деградация» коммуникации от документации до устного общения происходит самостоятельно Документация не заводится сама
54. • «Деградация» коммуникации от документации до устного общения происходит самостоятельно • Но не наоборот Документация не заводится сама
55. • «Деградация» коммуникации от документации до устного общения происходит самостоятельно • Но не наоборот Документация не заводится сама
56. • «Деградация» коммуникации от документации до устного общения происходит самостоятельно • Но не наоборот • Документацию нужно насаждать! Документация не заводится сама
57. • Создание и обновление документации должно быть обернуто в четкие процессы • Так же, как тестирование, деплой, code review… Документация — это проектный процесс
59. Процесс строится вокруг артефакта
60. • Постановка задачи на создание (или обновление) документационного артефакта Процесс строится вокруг артефакта
61. • Постановка задачи на создание (или обновление) документационного артефакта • Точка во времени Процесс строится вокруг артефакта
62. • Постановка задачи на создание (или обновление) документационного артефакта • Точка во времени • Требования к артефакту и решаемая задача Процесс строится вокруг артефакта
63. • Постановка задачи на создание (или обновление) документационного артефакта • Точка во времени • Требования к артефакту и решаемая задача Процесс строится вокруг артефакта
64. • Постановка задачи на создание (или обновление) документационного артефакта • Точка во времени • Требования к артефакту и решаемая задача • Контроль качества: точно ли созданный артефакт соответствует поставленной задаче? Процесс строится вокруг артефакта
65. • Каких двух стейкхолдеров мы связываем и зачем? • Какую информацию нужно передать? • Как лучше оформить эту информацию? Постановка задачи на создание документационного артефакта
66. • Каких двух стейкхолдеров мы связываем и зачем? • Какую информацию нужно передать? • Как лучше оформить эту информацию? Постановка задачи на создание документационного артефакта Бизнес
67. • Каких двух стейкхолдеров мы связываем и зачем? • Какую информацию нужно передать? • Как лучше оформить эту информацию? Постановка задачи на создание документационного артефакта Бизнес Оба стейкхолдера
68. • Каких двух стейкхолдеров мы связываем и зачем? • Какую информацию нужно передать? • Как лучше оформить эту информацию? Постановка задачи на создание документационного артефакта Бизнес Оба стейкхолдера Техписатель
69. • Любой технический документ — полноценный проектный артефакт • В постановке задачи на его создание участвуют • бизнес • оба стейкхолдера коммуникации • техписатель • Постановка задачи должна быть кем-то скоординирована Документ = артефакт
70. Инструментом постановки задачи на создание технического документа могут быть типовые шаблоны документов
71. Инструментом постановки задачи на создание технического документа могут быть типовые шаблоны документов Или примеры типовых документов
72. • Техзадание, высокоуровневые бизнес-требования • SRS, функциональные и нефункциональные требования • Инструкция по развертыванию рабочего окружения • Инструкция по развертыванию продукта • Руководство пользователя • Документация на API • Архитектура решения • Онбординг новому сотруднику Чеклист документации для IT-продукта Документ Кому он адресован Зачем он Техзадание (высокоуровневые бизнес- требования) Бизнесовые стейкхолдеры Снижение риска «сделать не то» SRS, спецификация требований (функциональных и нефункциональных) Команда разработки Снижение риска «сделать не то» Инструкция по настройке рабочего окружения Программисты Ускорение онбординга Инструкция по установке/развертыванию Интеграторы клиента Снижение нагрузки на техподдержку Руководство пользователя Конечные пользователи Снижение нагрузки на техподдержку Документация на API: справочник, вводные/обучающие статьи Программисты (внешние и внутренние) Снижение нагрузки на команду разработки Архитектурного программного решения: структура компонентов, модулей, классов… Программисты Ускорение онбординга Документ «первого дня» для нового сотрудника: о чем проект, ссылки на основные ресурсы, ссылки на документацию… Программисты Ускорение онбординга
73. Исходя из своих нужд команда может порождать примеры и шаблоны документов Но не наоборот
74. Критерии качества документации
75. • Полнота: этот канал передает всю необходимую информацию? Критерии качества документации
76. • Полнота: этот канал передает всю необходимую информацию? Критерии качества документации
77. • Полнота: этот канал передает всю необходимую информацию? • Корректность: этот канал передает верную и не устаревшую информацию? Критерии качества документации
78. • Полнота: этот канал передает всю необходимую информацию? • Корректность: этот канал передает верную и не устаревшую информацию? Критерии качества документации
79. • Полнота: этот канал передает всю необходимую информацию? • Корректность: этот канал передает верную и не устаревшую информацию? • Эффективность: извлечь информацию из этого канала дешевле, чем спросить устно или в чате? Критерии качества документации
80. • Полнота: этот канал передает всю необходимую информацию? • Корректность: этот канал передает верную и не устаревшую информацию? • Эффективность: извлечь информацию из этого канала дешевле, чем спросить устно или в чате? Критерии качества документации Стейкхолдеры
81. • Полнота: этот канал передает всю необходимую информацию? • Корректность: этот канал передает верную и не устаревшую информацию? • Эффективность: извлечь информацию из этого канала дешевле, чем спросить устно или в чате? Критерии качества документации Стейкхолдеры Стейкхолдеры
82. • Полнота: этот канал передает всю необходимую информацию? • Корректность: этот канал передает верную и не устаревшую информацию? • Эффективность: извлечь информацию из этого канала дешевле, чем спросить устно или в чате? Критерии качества документации Стейкхолдеры Стейкхолдеры Бизнес
83. • Полнота: этот канал передает всю необходимую информацию? • Корректность: этот канал передает верную и не устаревшую информацию? • Эффективность: извлечь информацию из этого канала дешевле, чем спросить устно или в чате? Критерии качества документации Стейкхолдеры Стейкхолдеры Техписатели
84. • Любой технический документ — полноценный проектный артефакт • В проверке его качества (т.е. того, что он соответствует поставленной задаче) участвуют • оба стейкхолдера коммуникации • техписатель • Проверка качества должна быть кем-то скоординирована Документ = артефакт
85. Документация — процесс и артефакт
86. • Постановка задачи Документация — процесс и артефакт
87. • Постановка задачи • Привязка к другим проектным процессам: в какой момент нужно ставить задачу на его создание? Документация — процесс и артефакт
88. • Постановка задачи • Привязка к другим проектным процессам: в какой момент нужно ставить задачу на его создание? • Критерии качества Документация — процесс и артефакт
89. • Постановка задачи • Привязка к другим проектным процессам: в какой момент нужно ставить задачу на его создание? • Критерии качества • Процессы проверки качества (обсудим в следующей серии) Документация — процесс и артефакт
90. • Ее нет • Есть, но никто не читает • Читают, но грустят при этом (плохо написана, тяжело читается…) • Читают, но все равно приходят с вопросами • Неполна, содержит не всю необходимую информацию • Устаревшая или содержит ошибки Типичные проблемы с документацией
91. • Ее нет • Есть, но никто не читает • Читают, но грустят при этом (плохо написана, тяжело читается…) • Читают, но все равно приходят с вопросами • Неполна, содержит не всю необходимую информацию • Устаревшая или содержит ошибки Типичные проблемы с документацией
92. Документацию никто не читает
93. • «Барьер входа» в документацию настолько велик, что дешевле пойти и спросить устно Документацию никто не читает
94. • «Барьер входа» в документацию настолько велик, что дешевле пойти и спросить устно • Неструктурированный массив PDF-ок на корпоративном диске Документацию никто не читает
95. • «Барьер входа» в документацию настолько велик, что дешевле пойти и спросить устно • Неструктурированный массив PDF-ок на корпоративном диске • 400-страничный DOCX, который страшно открывать Документацию никто не читает
96. • «Барьер входа» в документацию настолько велик, что дешевле пойти и спросить устно • Неструктурированный массив PDF-ок на корпоративном диске • 400-страничный DOCX, который страшно открывать • Confluence c 10 000 страниц, в котором непонятно, как искать Документацию никто не читает
97. • «Барьер входа» в документацию настолько велик, что дешевле пойти и спросить устно • Неструктурированный массив PDF-ок на корпоративном диске • 400-страничный DOCX, который страшно открывать • Confluence c 10 000 страниц, в котором непонятно, как искать • Документация размазана по разным хранилищам (Confluence, Google Docs, Markdown-файлы в репозитории…) Документацию никто не читает
98. • Продуманная структура корпоративной wiki • Маленькие статьи вместо 400-страничного DOCX • Единая платформа хранения документации и единая точка входа в нее Снижение «барьера входа» в документацию
99. • Стиль, язык, грамотность, структура текста тоже важны • Плохо читаемый (а тем более безграмотный) текст, неудобно структурированный документ спровоцирует читателя пойти и спросить устно Снижение «барьера входа» в документацию
100. • Продумать и поддерживать структуру хранения и представления документации • Подсказывать коллегам, куда лучше положить новый документ • Писать ясно (и грамотно), чтобы читать было удобнее, чем спрашивать устно Снижение «барьера входа» в документацию — задача техписателя
101. Подытожим
102. Документация — артефакт и процесс Подытожим
103. Подытожим
104. • Документация как способ реализации канала коммуникации — проектный артефакт Подытожим
105. • Документация как способ реализации канала коммуникации — проектный артефакт • Создание этих артефактов, равно как и проверка их качества должно регламентироваться отдельными процессами Подытожим
106. • Документация как способ реализации канала коммуникации — проектный артефакт • Создание этих артефактов, равно как и проверка их качества должно регламентироваться отдельными процессами • Техписатель — имплементатор канала коммуникации в рамках заданной задачи и с необходимой эффективностью Подытожим
107. • Документация как способ реализации канала коммуникации — проектный артефакт • Создание этих артефактов, равно как и проверка их качества должно регламентироваться отдельными процессами • Техписатель — имплементатор канала коммуникации в рамках заданной задачи и с необходимой эффективностью • Координация процессов вокруг документации — не в ведении техписателя Подытожим
108. • Чуть подробнее о процессах работы с документацией • Жизненные циклы технических документов В следующей серии
109. • Консалтинг и настройка процессов документирования • Заказная разработка документации • Бесплатный аудит вашей документации Обязательная минутка рекламы www.documentat.io