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

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

Технический документ — это… проектный артефакт технической документации, связывающий двух определенных стейкхолдеров и являющийся обособленной единицей в терминах •целеполагания, •контроля качества, •и публикации.

Slide 5

Slide 5 text

Технический документ — проектный артефакт технической документации, связывающий двух определенных стейкхолдеров и являющийся обособленной единицей в терминах •целеполагания, •контроля качества, •и публикации.

Slide 6

Slide 6 text

Артефакт + процесс вокруг него = жизненный цикл

Slide 7

Slide 7 text

No content

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

No content

Slide 16

Slide 16 text

No content

Slide 17

Slide 17 text

— Где последняя спека? — Переписка «RE: RE: FWD: Последняя версия с правками» от 12 февраля 2020

Slide 18

Slide 18 text

No content

Slide 19

Slide 19 text

— Где последняя спека? — //share.local/Project/Specs/SRS.docx

Slide 20

Slide 20 text

А как же история ревизий?

Slide 21

Slide 21 text

No content

Slide 22

Slide 22 text

No content

Slide 23

Slide 23 text

— Где последняя спека? — Наша корпоративная общая папка в Dropbox, а дальше /Project/Specs/Mega_Project_SRS.docx

Slide 24

Slide 24 text

No content

Slide 25

Slide 25 text

Требования к инструментарию хранения

Slide 26

Slide 26 text

• Однозначная локация документа (файл в репозитории, URL…) Требования к инструментарию хранения

Slide 27

Slide 27 text

• Однозначная локация документа (файл в репозитории, URL…) • Автоматически поддерживаемая история ревизий Требования к инструментарию хранения

Slide 28

Slide 28 text

• Однозначная локация документа (файл в репозитории, URL…) • Автоматически поддерживаемая история ревизий • Обнаруживаемость (discoverability): возможность увидеть весь список документов Требования к инструментарию хранения

Slide 29

Slide 29 text

Инструментарий ревью

Slide 30

Slide 30 text

Инструментарий ревью

Slide 31

Slide 31 text

• Комментарии (желательно, к фрагменту текста, а не ко всему тексту) • Workflow комментариев: закрытие, переоткрытие, ветки дискуссий… • Точечное отслеживание изменений: что же поменялось с предыдущей ревизии? Инструментарий ревью

Slide 32

Slide 32 text

Slide 33

Slide 33 text

Slide 34

Slide 34 text

• Однозначная локация документа (файл в репозитории, URL…) • Автоматически поддерживаемая история ревизий И снова хранение

Slide 35

Slide 35 text

• Однозначная локация документа (файл в репозитории, URL…) • Автоматически поддерживаемая история ревизий И снова хранение Все это очень сильно облегчает ревью

Slide 36

Slide 36 text

Slide 37

Slide 37 text

Инструментарий ревью не создаст вам процессы ревью

Slide 38

Slide 38 text

Cовместное одновременное редактирование не нужно

Slide 39

Slide 39 text

Подходящие инструменты на данный момент

Slide 40

Slide 40 text

• Google Docs Подходящие инструменты на данный момент

Slide 41

Slide 41 text

• Google Docs • Confluence Подходящие инструменты на данный момент

Slide 42

Slide 42 text

• Google Docs • Confluence • MS Word + Office365 + OneDrive Подходящие инструменты на данный момент

Slide 43

Slide 43 text

• Google Docs • Confluence • MS Word + Office365 + OneDrive Подходящие инструменты на данный момент + Процессы ревью и регламенты хранения

Slide 44

Slide 44 text

• Конвертация во что-то удобочитаемое • PDF • HTML • Красивый DOCX Инструменты публикации

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

• Переиспользование контента • Блоки текста • Текстовые переменные • Строгое соответствие визуальным шаблонам (ГОСТ, корпоративная айдентика) Инструменты разработки

Slide 50

Slide 50 text

• Переиспользование контента • Блоки текста • Текстовые переменные • Строгое соответствие визуальным шаблонам (ГОСТ, корпоративная айдентика) • Скорость создания контента Инструменты разработки

Slide 51

Slide 51 text

Slide 52

Slide 52 text

Slide 53

Slide 53 text

• Author-it • MadCap Flare • Help&Manual Help Authoring Tools, HATs

Slide 54

Slide 54 text

• В первую очередь инструментарий разработки • Процессы ревью, подходы к хранению и пр. вторичны Help Authoring Tools, HATs

Slide 55

Slide 55 text

• В меньшей степени применимы для «быстрых» документов • Барьер входа в создание документации высок Help Authoring Tools, HATs

Slide 56

Slide 56 text

Специфические желания

Slide 57

Slide 57 text

• Сравнение произвольных ревизий Специфические желания

Slide 58

Slide 58 text

• Сравнение произвольных ревизий • Blame: кто автор этой строчки? Специфические желания

Slide 59

Slide 59 text

• Сравнение произвольных ревизий • Blame: кто автор этой строчки? • Синхронизация изменений в коде и изменений в документации Специфические желания

Slide 60

Slide 60 text

• Сравнение произвольных ревизий • Blame: кто автор этой строчки? • Синхронизация изменений в коде и изменений в документации • Автоматизированная публикация Специфические желания

Slide 61

Slide 61 text

• Давайте относиться к документации как к коду! • Хранить ее в plain text в репозитории Docs as code

Slide 62

Slide 62 text

• Легковесные языки разметки • Markdown • Asciidoc • RST Docs as code

Slide 63

Slide 63 text

• Экосистема инструментария конвертации и публикации • PDF • Многостраничный HTML • DOCX Docs as code

Slide 64

Slide 64 text

• Большинство инструментов публикации • бесплатны • открыты • встраиваются в CI/CD-конвейеры Docs as code

Slide 65

Slide 65 text

• Все преимущества Git • diff • blame • merge Docs as code

Slide 66

Slide 66 text

Модели ветвления, Git workflows

Slide 67

Slide 67 text

• Давайте переиспользуем инструментарий для кода! • Pull/merge requests в вашем любимом GitHub/ GitLab/Bitbucket Ревью в docs as code?

Slide 68

Slide 68 text

Docs as code, плюсы

Slide 69

Slide 69 text

• Невероятная гибкость инструментария Docs as code, плюсы

Slide 70

Slide 70 text

• Невероятная гибкость инструментария • Синхронизация изменений в коде и в документации Docs as code, плюсы

Slide 71

Slide 71 text

• Невероятная гибкость инструментария • Синхронизация изменений в коде и в документации • Автоматизация публикации «из коробки» Docs as code, плюсы

Slide 72

Slide 72 text

Docs as code, минусы

Slide 73

Slide 73 text

• Ревью не всегда удобно Docs as code, минусы

Slide 74

Slide 74 text

• Ревью не всегда удобно • Высокая стоимость первичной настройки Docs as code, минусы

Slide 75

Slide 75 text

• Ревью не всегда удобно • Высокая стоимость первичной настройки • Все еще высокий барьер создания документации Docs as code, минусы

Slide 76

Slide 76 text

• Ревью не всегда удобно • Высокая стоимость первичной настройки • Все еще высокий барьер создания документации • Иногда очень не хватает WYSIWYG:( Docs as code, минусы

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

• Скорее всего, вы будете смотреть в сторону чего-то одного • Коллаборативный WYSIWYG (Google Docs, Office365, Confluence…) Подытожим

Slide 87

Slide 87 text

• Скорее всего, вы будете смотреть в сторону чего-то одного • Коллаборативный WYSIWYG (Google Docs, Office365, Confluence…) • Help Authoring Tools Подытожим

Slide 88

Slide 88 text

• Скорее всего, вы будете смотреть в сторону чего-то одного • Коллаборативный WYSIWYG (Google Docs, Office365, Confluence…) • Help Authoring Tools • Docs as code Подытожим

Slide 89

Slide 89 text

• Выбор инструментального стека – не навсегда • Миграция с DOCX на docs as code • Миграция с DOCX на Confluence Подытожим

Slide 90

Slide 90 text

• Выбор инструментального стека – не навсегда • Миграция с DOCX на docs as code • Миграция с DOCX на Confluence Подытожим www.documentat.io

Slide 91

Slide 91 text

• DITA и DocBook, стандарты и экосистемы инструментария разработки документации • Инструментарий управления переводами О чем еще не поговорили

Slide 92

Slide 92 text

• DITA/DocBook, стандарт и экосистема инструментария • Help Authoring Tools на конкретных примерах • Docs as code как философия • Docs as code на конкретных примерах О чем обязательно поговорим

Slide 93

Slide 93 text

DocOps как расширение идеи docs as code Николай Волынкин (Plesk) В следующей серии