Tweet
Tweet

Slide 1

Slide 1 text

www.documentat.io Семëн Факторович sam@documentat.io Техническая документация в IT-проектах

Slide 2

Slide 2 text

• Консалтинг и настройка процессов документирования • Заказная разработка документации • Бесплатный аудит вашей документации Обязательная минутка рекламы www.documentat.io

Slide 3

Slide 3 text

В предыдущей серии

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

Спецификация требований Техзадание Техзадание Справочник API Архитектура решения Руководство пользователя Troubleshooting guide

Slide 6

Slide 6 text

• Документация — способ реализации канала коммуникации между парой стейкхолдеров • Документация нужна тогда, когда другие способы реализации этого канала более дороги или рискованны • Если документация реализует коммуникацию не очень эффективно, то стейкхолдеры перейдут к другим вариантам — например, устным В предыдущей серии

Slide 7

Slide 7 text

• Типичные проблемы с документацией и откуда они растут • Техническая документация — процесс или артефакт? Да! О чем будем говорить сегодня

Slide 8

Slide 8 text

Типичные проблемы с документацией

Slide 9

Slide 9 text

• Ее нет Типичные проблемы с документацией

Slide 10

Slide 10 text

• Ее нет • Есть, но никто не читает Типичные проблемы с документацией

Slide 11

Slide 11 text

• Ее нет • Есть, но никто не читает • Читают, но грустят при этом (плохо написана, тяжело читается…) Типичные проблемы с документацией

Slide 12

Slide 12 text

• Ее нет • Есть, но никто не читает • Читают, но грустят при этом (плохо написана, тяжело читается…) • Читают, но все равно приходят с вопросами Типичные проблемы с документацией

Slide 13

Slide 13 text

• Ее нет • Есть, но никто не читает • Читают, но грустят при этом (плохо написана, тяжело читается…) • Читают, но все равно приходят с вопросами • Неполна, содержит не всю необходимую информацию Типичные проблемы с документацией

Slide 14

Slide 14 text

• Ее нет • Есть, но никто не читает • Читают, но грустят при этом (плохо написана, тяжело читается…) • Читают, но все равно приходят с вопросами • Неполна, содержит не всю необходимую информацию • Устаревшая или содержит ошибки Типичные проблемы с документацией

Slide 15

Slide 15 text

• Ее нет • Есть, но никто не читает • Читают, но грустят при этом (плохо написана, тяжело читается…) • Читают, но все равно приходят с вопросами • Неполна, содержит не всю необходимую информацию • Устаревшая или содержит ошибки Типичные проблемы с документацией

Slide 16

Slide 16 text

Документации нет

Slide 17

Slide 17 text

• Все понимают, что она нужна, но никто ее не пишет Документации нет

Slide 18

Slide 18 text

• Все понимают, что она нужна, но никто ее не пишет • Никто не ставит задачу на ее написание Документации нет

Slide 19

Slide 19 text

• Все понимают, что она нужна, но никто ее не пишет • Никто не ставит задачу на ее написание Документации нет

Slide 20

Slide 20 text

• Все понимают, что она нужна, но никто ее не пишет • Никто не ставит задачу на ее написание • Никто не понимает, зачем она нужна (и, соответственно, не пишут) Документации нет

Slide 21

Slide 21 text

Иногда документация действительно не нужна

Slide 22

Slide 22 text

Иногда документация действительно не нужна

Slide 23

Slide 23 text

Иногда документация действительно не нужна

Slide 24

Slide 24 text

• Другие каналы коммуникации (realtime, push) дешевле, чем документация Иногда документация действительно не нужна

Slide 25

Slide 25 text

• Другие каналы коммуникации (realtime, push) дешевле, чем документация Иногда документация действительно не нужна

Slide 26

Slide 26 text

• Другие каналы коммуникации (realtime, push) дешевле, чем документация • Этих двух стейкхолдеров не нужно связывать — канал коммуникации между ними не важен для бизнеса Иногда документация действительно не нужна

Slide 27

Slide 27 text

Иногда документация действительно не нужна

Slide 28

Slide 28 text

• «Онбординг новых сотрудников мы проводим устно» Иногда документация действительно не нужна

Slide 29

Slide 29 text

• «Онбординг новых сотрудников мы проводим устно» Иногда документация действительно не нужна

Slide 30

Slide 30 text

• «Онбординг новых сотрудников мы проводим устно» • «Мы не документируем схему БД, потому что ее можно построить в один клик» Иногда документация действительно не нужна

Slide 31

Slide 31 text

• «Онбординг новых сотрудников мы проводим устно» • «Мы не документируем схему БД, потому что ее можно построить в один клик» Иногда документация действительно не нужна

Slide 32

Slide 32 text

• «Онбординг новых сотрудников мы проводим устно» • «Мы не документируем схему БД, потому что ее можно построить в один клик» • «Наш продукт достаточно прост, ему не нужна пользовательская документация» Иногда документация действительно не нужна

Slide 33

Slide 33 text

Аудит существующей документации

Slide 34

Slide 34 text

Аудит существующей документации

Slide 35

Slide 35 text

• Действительно ли каждый ваш документационный артефакт связывает пару стейкхолдеров? Аудит существующей документации

Slide 36

Slide 36 text

• Действительно ли каждый ваш документационный артефакт связывает пару стейкхолдеров? Аудит существующей документации

Slide 37

Slide 37 text

• Действительно ли каждый ваш документационный артефакт связывает пару стейкхолдеров? • Действительно ли этим двум стейкхолдерам нужна именно документация, а не устное общение? Аудит существующей документации

Slide 38

Slide 38 text

Документацию никто не пишет

Slide 39

Slide 39 text

• Архитектура и дизайн-решения новых фич не документируются (или документируются, но не всегда) Документацию никто не пишет

Slide 40

Slide 40 text

• Архитектура и дизайн-решения новых фич не документируются (или документируются, но не всегда) Документацию никто не пишет

Slide 41

Slide 41 text

• Архитектура и дизайн-решения новых фич не документируются (или документируются, но не всегда) • Изменения в требованиях от заказчика не фиксируются в спецификации требований Документацию никто не пишет

Slide 42

Slide 42 text

• Архитектура и дизайн-решения новых фич не документируются (или документируются, но не всегда) • Изменения в требованиях от заказчика не фиксируются в спецификации требований Документацию никто не пишет

Slide 43

Slide 43 text

• Архитектура и дизайн-решения новых фич не документируются (или документируются, но не всегда) • Изменения в требованиях от заказчика не фиксируются в спецификации требований • Руководство пользователя безнадежно отстало от текущего состояния продукта Документацию никто не пишет

Slide 44

Slide 44 text

В параллельной вселенной

Slide 45

Slide 45 text

• «Мы пофиксали баг, но забыли выкатить этот фикс на прод» В параллельной вселенной

Slide 46

Slide 46 text

• «Мы пофиксали баг, но забыли выкатить этот фикс на прод» В параллельной вселенной

Slide 47

Slide 47 text

• «Мы пофиксали баг, но забыли выкатить этот фикс на прод» • «Новые фичи почему-то не тестируются» В параллельной вселенной

Slide 48

Slide 48 text

• «Мы пофиксали баг, но забыли выкатить этот фикс на прод» • «Новые фичи почему-то не тестируются» В параллельной вселенной

Slide 49

Slide 49 text

• «Мы пофиксали баг, но забыли выкатить этот фикс на прод» • «Новые фичи почему-то не тестируются» • «Иногда мы не забываем делать code review, но чаще всего все-таки забываем» В параллельной вселенной

Slide 50

Slide 50 text

Принципиальные активности разработки (code review, тестирование, деплой) обернуты в процессы В нашей вселенной

Slide 51

Slide 51 text

Документация не заводится сама

Slide 52

Slide 52 text

• «Деградация» коммуникации от документации до устного общения происходит самостоятельно Документация не заводится сама

Slide 53

Slide 53 text

• «Деградация» коммуникации от документации до устного общения происходит самостоятельно Документация не заводится сама

Slide 54

Slide 54 text

• «Деградация» коммуникации от документации до устного общения происходит самостоятельно • Но не наоборот Документация не заводится сама

Slide 55

Slide 55 text

• «Деградация» коммуникации от документации до устного общения происходит самостоятельно • Но не наоборот Документация не заводится сама

Slide 56

Slide 56 text

• «Деградация» коммуникации от документации до устного общения происходит самостоятельно • Но не наоборот • Документацию нужно насаждать! Документация не заводится сама

Slide 57

Slide 57 text

• Создание и обновление документации должно быть обернуто в четкие процессы • Так же, как тестирование, деплой, code review… Документация — это проектный процесс

Slide 58

Slide 58 text

No content

Slide 59

Slide 59 text

Процесс строится вокруг артефакта

Slide 60

Slide 60 text

• Постановка задачи на создание (или обновление) документационного артефакта Процесс строится вокруг артефакта

Slide 61

Slide 61 text

• Постановка задачи на создание (или обновление) документационного артефакта • Точка во времени Процесс строится вокруг артефакта

Slide 62

Slide 62 text

• Постановка задачи на создание (или обновление) документационного артефакта • Точка во времени • Требования к артефакту и решаемая задача Процесс строится вокруг артефакта

Slide 63

Slide 63 text

• Постановка задачи на создание (или обновление) документационного артефакта • Точка во времени • Требования к артефакту и решаемая задача Процесс строится вокруг артефакта

Slide 64

Slide 64 text

• Постановка задачи на создание (или обновление) документационного артефакта • Точка во времени • Требования к артефакту и решаемая задача • Контроль качества: точно ли созданный артефакт соответствует поставленной задаче? Процесс строится вокруг артефакта

Slide 65

Slide 65 text

• Каких двух стейкхолдеров мы связываем и зачем? • Какую информацию нужно передать? • Как лучше оформить эту информацию? Постановка задачи на создание документационного артефакта

Slide 66

Slide 66 text

• Каких двух стейкхолдеров мы связываем и зачем? • Какую информацию нужно передать? • Как лучше оформить эту информацию? Постановка задачи на создание документационного артефакта Бизнес

Slide 67

Slide 67 text

• Каких двух стейкхолдеров мы связываем и зачем? • Какую информацию нужно передать? • Как лучше оформить эту информацию? Постановка задачи на создание документационного артефакта Бизнес Оба стейкхолдера

Slide 68

Slide 68 text

• Каких двух стейкхолдеров мы связываем и зачем? • Какую информацию нужно передать? • Как лучше оформить эту информацию? Постановка задачи на создание документационного артефакта Бизнес Оба стейкхолдера Техписатель

Slide 69

Slide 69 text

• Любой технический документ — полноценный проектный артефакт • В постановке задачи на его создание участвуют • бизнес • оба стейкхолдера коммуникации • техписатель • Постановка задачи должна быть кем-то скоординирована Документ = артефакт

Slide 70

Slide 70 text

Инструментом постановки задачи на создание технического документа могут быть типовые шаблоны документов

Slide 71

Slide 71 text

Инструментом постановки задачи на создание технического документа могут быть типовые шаблоны документов Или примеры типовых документов

Slide 72

Slide 72 text

• Техзадание, высокоуровневые бизнес-требования • SRS, функциональные и нефункциональные требования • Инструкция по развертыванию рабочего окружения • Инструкция по развертыванию продукта • Руководство пользователя • Документация на API • Архитектура решения • Онбординг новому сотруднику Чеклист документации для IT-продукта Документ Кому он адресован Зачем он Техзадание (высокоуровневые бизнес- требования) Бизнесовые стейкхолдеры Снижение риска «сделать не то» SRS, спецификация требований (функциональных и нефункциональных) Команда разработки Снижение риска «сделать не то» Инструкция по настройке рабочего окружения Программисты Ускорение онбординга Инструкция по установке/развертыванию Интеграторы клиента Снижение нагрузки на техподдержку Руководство пользователя Конечные пользователи Снижение нагрузки на техподдержку Документация на API: справочник, вводные/обучающие статьи Программисты (внешние и внутренние) Снижение нагрузки на команду разработки Архитектурного программного решения: структура компонентов, модулей, классов… Программисты Ускорение онбординга Документ «первого дня» для нового сотрудника: о чем проект, ссылки на основные ресурсы, ссылки на документацию… Программисты Ускорение онбординга

Slide 73

Slide 73 text

Исходя из своих нужд команда может порождать примеры и шаблоны документов Но не наоборот

Slide 74

Slide 74 text

Критерии качества документации

Slide 75

Slide 75 text

• Полнота: этот канал передает всю необходимую информацию? Критерии качества документации

Slide 76

Slide 76 text

• Полнота: этот канал передает всю необходимую информацию? Критерии качества документации

Slide 77

Slide 77 text

• Полнота: этот канал передает всю необходимую информацию? • Корректность: этот канал передает верную и не устаревшую информацию? Критерии качества документации

Slide 78

Slide 78 text

• Полнота: этот канал передает всю необходимую информацию? • Корректность: этот канал передает верную и не устаревшую информацию? Критерии качества документации

Slide 79

Slide 79 text

• Полнота: этот канал передает всю необходимую информацию? • Корректность: этот канал передает верную и не устаревшую информацию? • Эффективность: извлечь информацию из этого канала дешевле, чем спросить устно или в чате? Критерии качества документации

Slide 80

Slide 80 text

• Полнота: этот канал передает всю необходимую информацию? • Корректность: этот канал передает верную и не устаревшую информацию? • Эффективность: извлечь информацию из этого канала дешевле, чем спросить устно или в чате? Критерии качества документации Стейкхолдеры

Slide 81

Slide 81 text

• Полнота: этот канал передает всю необходимую информацию? • Корректность: этот канал передает верную и не устаревшую информацию? • Эффективность: извлечь информацию из этого канала дешевле, чем спросить устно или в чате? Критерии качества документации Стейкхолдеры Стейкхолдеры

Slide 82

Slide 82 text

• Полнота: этот канал передает всю необходимую информацию? • Корректность: этот канал передает верную и не устаревшую информацию? • Эффективность: извлечь информацию из этого канала дешевле, чем спросить устно или в чате? Критерии качества документации Стейкхолдеры Стейкхолдеры Бизнес

Slide 83

Slide 83 text

• Полнота: этот канал передает всю необходимую информацию? • Корректность: этот канал передает верную и не устаревшую информацию? • Эффективность: извлечь информацию из этого канала дешевле, чем спросить устно или в чате? Критерии качества документации Стейкхолдеры Стейкхолдеры Техписатели

Slide 84

Slide 84 text

• Любой технический документ — полноценный проектный артефакт • В проверке его качества (т.е. того, что он соответствует поставленной задаче) участвуют • оба стейкхолдера коммуникации • техписатель • Проверка качества должна быть кем-то скоординирована Документ = артефакт

Slide 85

Slide 85 text

Документация — процесс и артефакт

Slide 86

Slide 86 text

• Постановка задачи Документация — процесс и артефакт

Slide 87

Slide 87 text

• Постановка задачи • Привязка к другим проектным процессам: в какой момент нужно ставить задачу на его создание? Документация — процесс и артефакт

Slide 88

Slide 88 text

• Постановка задачи • Привязка к другим проектным процессам: в какой момент нужно ставить задачу на его создание? • Критерии качества Документация — процесс и артефакт

Slide 89

Slide 89 text

• Постановка задачи • Привязка к другим проектным процессам: в какой момент нужно ставить задачу на его создание? • Критерии качества • Процессы проверки качества (обсудим в следующей серии) Документация — процесс и артефакт

Slide 90

Slide 90 text

• Ее нет • Есть, но никто не читает • Читают, но грустят при этом (плохо написана, тяжело читается…) • Читают, но все равно приходят с вопросами • Неполна, содержит не всю необходимую информацию • Устаревшая или содержит ошибки Типичные проблемы с документацией

Slide 91

Slide 91 text

• Ее нет • Есть, но никто не читает • Читают, но грустят при этом (плохо написана, тяжело читается…) • Читают, но все равно приходят с вопросами • Неполна, содержит не всю необходимую информацию • Устаревшая или содержит ошибки Типичные проблемы с документацией

Slide 92

Slide 92 text

Документацию никто не читает

Slide 93

Slide 93 text

• «Барьер входа» в документацию настолько велик, что дешевле пойти и спросить устно Документацию никто не читает

Slide 94

Slide 94 text

• «Барьер входа» в документацию настолько велик, что дешевле пойти и спросить устно • Неструктурированный массив PDF-ок на корпоративном диске Документацию никто не читает

Slide 95

Slide 95 text

• «Барьер входа» в документацию настолько велик, что дешевле пойти и спросить устно • Неструктурированный массив PDF-ок на корпоративном диске • 400-страничный DOCX, который страшно открывать Документацию никто не читает

Slide 96

Slide 96 text

• «Барьер входа» в документацию настолько велик, что дешевле пойти и спросить устно • Неструктурированный массив PDF-ок на корпоративном диске • 400-страничный DOCX, который страшно открывать • Confluence c 10 000 страниц, в котором непонятно, как искать Документацию никто не читает

Slide 97

Slide 97 text

• «Барьер входа» в документацию настолько велик, что дешевле пойти и спросить устно • Неструктурированный массив PDF-ок на корпоративном диске • 400-страничный DOCX, который страшно открывать • Confluence c 10 000 страниц, в котором непонятно, как искать • Документация размазана по разным хранилищам (Confluence, Google Docs, Markdown-файлы в репозитории…) Документацию никто не читает

Slide 98

Slide 98 text

• Продуманная структура корпоративной wiki • Маленькие статьи вместо 400-страничного DOCX • Единая платформа хранения документации и единая точка входа в нее Снижение «барьера входа» в документацию

Slide 99

Slide 99 text

• Стиль, язык, грамотность, структура текста тоже важны • Плохо читаемый (а тем более безграмотный) текст, неудобно структурированный документ спровоцирует читателя пойти и спросить устно Снижение «барьера входа» в документацию

Slide 100

Slide 100 text

• Продумать и поддерживать структуру хранения и представления документации • Подсказывать коллегам, куда лучше положить новый документ • Писать ясно (и грамотно), чтобы читать было удобнее, чем спрашивать устно Снижение «барьера входа» в документацию — задача техписателя

Slide 101

Slide 101 text

Подытожим

Slide 102

Slide 102 text

Документация — артефакт и процесс Подытожим

Slide 103

Slide 103 text

Подытожим

Slide 104

Slide 104 text

• Документация как способ реализации канала коммуникации — проектный артефакт Подытожим

Slide 105

Slide 105 text

• Документация как способ реализации канала коммуникации — проектный артефакт • Создание этих артефактов, равно как и проверка их качества должно регламентироваться отдельными процессами Подытожим

Slide 106

Slide 106 text

• Документация как способ реализации канала коммуникации — проектный артефакт • Создание этих артефактов, равно как и проверка их качества должно регламентироваться отдельными процессами • Техписатель — имплементатор канала коммуникации в рамках заданной задачи и с необходимой эффективностью Подытожим

Slide 107

Slide 107 text

• Документация как способ реализации канала коммуникации — проектный артефакт • Создание этих артефактов, равно как и проверка их качества должно регламентироваться отдельными процессами • Техписатель — имплементатор канала коммуникации в рамках заданной задачи и с необходимой эффективностью • Координация процессов вокруг документации — не в ведении техписателя Подытожим

Slide 108

Slide 108 text

• Чуть подробнее о процессах работы с документацией • Жизненные циклы технических документов В следующей серии

Slide 109

Slide 109 text

• Консалтинг и настройка процессов документирования • Заказная разработка документации • Бесплатный аудит вашей документации Обязательная минутка рекламы www.documentat.io