Вам Кажется, Что С Вашей Документацией Что-То Не Так? Ты Не Думаешь

Меня зовут Семен Факторович, с 2012 года занимаюсь технической документацией.

Последние три года я управляю собственным агентством.

documentat.io , помогая российским ИТ-компаниям создавать качественную документацию.

Пишем документацию с нуля (руководства пользователя, справочники по API, архитектурную документацию), поддерживаем существующие и консультируем по настройке процессов документирования.

И почти каждый запрос наших клиентов начинается с признания: «Кажется, что-то не так с нашей документацией».

Когда мы начинаем копать глубже и разбираться, что с этим не так, то очень часто причины совершенно одни и те же и повторяются от компании к компании.

Если объединить их в один список и отсортировать по частоте озвучивания, то получится следующий хит-парад проблем: 1) Документации нет вообще.

2) Документацию пишут неохотно.

3) Люди неохотно читают документацию.

4) Документация есть, она написана и прочитана, но кажется бесполезной.

Последний пункт требует пояснения: чаще всего за словом «бесполезный» скрывается ощущение, что Документация не очень хорошо справляется со своей задачей.

.

Потому что она либо не полный , то есть не описывает все аспекты, которые хотелось бы в нем найти.

Или не точный , то есть то, что там написано, не совсем верно.

Или не имеет значения , то есть в прошлом оно соответствовало истине, но сейчас изменилась программная система или внешний мир, и документация уже не соответствует этому.

Вот о каких проблемах я хочу сегодня поговорить: давайте рассмотрим их симптомы и то, как их интерпретировать, а главное, что с ними делать.

Предлагаю вам определенный метод самодиагностики и самостоятельного лечения проблем с вашей документацией.

Все, что представлено ниже, проверено в нескольких десятках ИТ-компаний.

Что такое документация?

Традиционно мы не рассматриваем техническую документацию:

• Лицензионные соглашения (EULA), которые мы никогда не читаем при установке программного обеспечения.

• Маркетинговые тексты, описывающие преимущества и функциональность продукта/услуги на сайте или в магазине приложений.

• Тексты в интерфейсе — надписи на кнопках, тексты в диалоговых окнах и т.д.

• Требования в той или иной форме, например, техническое задание или техническое задание (СТТ).

• Описание архитектуры программных решений.

• Документация по API.
• Инструкции по установке или развертыванию.

• Руководства пользователя.

• README.md для компонентов или библиотек, которые будут использовать ваши коллеги, соседние команды или другие компании.

В главе «Управление коммуникациями» говорится примерно следующее:

Внутри и вне команды проекта есть его значимые участники – стейкхолдеры.

Между ними есть каналы связи.

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

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

• Разработчик пишет документацию по API для своего пользователя.

• Принятие в команду нового разработчика вполне может включать изучение архитектурного документа системы.

• Консультируя пользователя в технической поддержке, он попросит его прочитать пользовательскую документацию.

Но это не единственный возможный способ общения между ними.

Например, клиент может общаться с бизнес-аналитиком голосом, онбординг также может осуществляться устно (что и происходит в большинстве случаев):



На самом деле есть много других способов, например: письма, переписка в мессенджерах, телефонные звонки.

Три очень реальные истории из моей практики:

• В одной из компаний, где я работал, видеозаписи были инструментом архитектурного онбординга.

  То есть прямо у доски провели onboarding одного нового сотрудника, нарисовали архитектуру системы и рассказали ее основные принципы.

  Это ловко было записано на видео, и всем последующим сотрудникам эту двухчасовую видеозапись раздали.

  Конечно, это способ реализовать общение с новым сотрудником.

  Можно ли это считать документацией – вопрос скользкий, но, наверное, да.

• Подслушанная история в кулуарах конференции: «Мы храним документацию по API в виде пяти телеграмм-сообщений, заботливо пересылаемых между сотрудниками».

• В другой компании специалисты DevOps описывают сетевую инфраструктуру с помощью голосовых сообщений WhatsApp. Таких сообщений уже накопилось довольно много, и только если их все прослушать, вырисовывается полная картина.

  Когда новый руководитель этого направления это понял, он решил объединить их, но отформатировать не как текст (например, статью на внутренней вики), а как подкаст.

Но такое «жесткое» общение стоит очень дорого:

• Его нужно написать, а это значительные затраты времени;
• Его необходимо поддерживать, поскольку он быстро устаревает и становится немного менее актуальным с каждым внесением в кодовую базу.

• Оно должно быть дешевле устного общения – и только в этом случае оно «взлетит».

Например, команда единогласно поймет, что если мы будем привлекать 10 новых людей в месяц, то каждый раз говорить одно и то же в Slack слишком накладно — давайте напишем наконец несколько статей на эту тему в вики (или запишем видео и назовем это документация).

Учитывая это, вернемся теперь к списку проблем из первого абзаца статьи.

Проблема №1: Нет документации

Это крутое осознание, которое требует очень серьезного размышления и понимания.

Возможно, с каким-то координатором (например, с представителем нашей компании), который будет задавать правильные вопросы и подталкивать вас к правильным ответам.

Чаще всего отсутствие документации означает, что какие-то абсолютно конкретные заинтересованные стороны не связаны каналом связи.

Либо этот канал общения устный, в Slack, посредством голосовых сообщений.

Если вы до сих пор не можете сформулировать, какой именно документации не хватает, и не можете понять, что с ней делать, то мой совет будет полностью «Дзен»:

1. Поймите, что документации нет.
2. Нарисуйте то, чего не хватает: карту заинтересованных сторон и недостающих каналов связи между ними.

Но нарисовав такую карту коммуникаций, вы многое поймете о том, как можно улучшить ситуацию с коммуникациями и документацией в вашем проекте.

Проблема №2: люди неохотно пишут документацию

Обычно мы слышим жалобы по этому поводу:

• Архитектура новых функций не документируется: наши разработчики не очень любят документировать свои проектные решения.

  Они что-то сделали, но не описали, почему и как они это сделали.

  Информация, конечно, не теряется (она есть в коде и в головах разработчиков), но восстановить ее сложно.

• Изменения требований не фиксируются: на старте проекта мы написали красивое техническое задание или техническое задание, но с тех пор требования изменились на 50%, и это нигде не фиксируется.

• Руководство пользователя безнадежно устарело: оно отражает состояние продукта пятилетней давности.

  Когда-то он был написан, и это было круто, но теперь он устарел, потому что мы не можем собраться с силами, чтобы обновить его.

Представьте себе, что в параллельной вселенной команда разработчиков жалуется на совершенно неконтролируемые истории: «мы исправили ошибку, но забыли выкатить это исправление на продакшен», «по какой-то причине новые функции не тестируются» или «иногда мы не тестируем».

Не забудьте сделать обзор кода».

С деплоем, тестированием и код-ревью у нас полный порядок, потому что все это является частью фундаментальной деятельности по развитию, и эта деятельность заключена в процессы .

Есть люди, которые следят за тем, чтобы эти процессы осуществлялись.

Проще говоря, вы не переведете карточку в состояние «готово» на канбан-доске или в Jira, пока она не пройдет состояние «тестирование» или «на рассмотрении».

Есть ли у вас процессы, связанные с документацией?

Это сложно, потому что мы очень плохо представляем себе, что такое «процессы вокруг документации».

Но этот вопрос можно разложить на два более простых:

1. На каких этапах других процессов вы пишете или обновляете документацию? То есть понимаете ли вы, на каком этапе разработки фичи вам нужно сесть и написать (или обновить) документацию, и какую документацию?
2. Каков жизненный цикл каждого из ваших документов? Имеет ли ваш технический документ (например, описание функции или руководство пользователя) какой-либо жизненный цикл? Есть ли ситуации, когда вы обновляете его? Вы понимаете, что его сейчас нужно обновить, или все и так нормально?

технический документ — это артефакт дизайна .

Как и код, примечания к выпуску, новые функции и весь продукт. И артефакт проекта должен содержать:

• Постановка задачи на его создание.

  Вы должны четко поставить задачу: «Создайте мне артефакт с такими-то свойствами».

  Какими свойствами должна обладать ваша документация?

• Жизненный цикл.

  Артефакт должен иметь жизненный цикл, потому что он не создается один раз, а развивается.

  Как для вас выглядит жизненный цикл каждого технического документа?

• Критерии качества, определения выполненного.

  Когда мы считаем руководство пользователя завершенным? Как определить, качественно это или нет?

Шаблоны и примеры документов

Очень немногие компании могут объективно и хорошо оценить, является ли их техническая документация высокого качества или нет. То же самое происходит и с постановкой задачи: «Опишем архитектуру нового компонента.

А вот такое «описание архитектуры», как его написать и как определить, что оно написано хорошо – непонятно.

Для таких ситуаций есть очень хороший инструмент — шаблоны, а еще лучше примеры готовых документов, которые создаются в команде (и вы знаете, как они выглядят):

• «Мы описываем архитектуру новой функции, используя этот шаблон».

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

• «Пример учебника по API» — когда вы создаете новый API, не забудьте не только покрыть его Swagger, но и написать для него учебник: как использовать этот API, почему этот API такой и что можно сделать достигнуто с его помощью.

  Дальше можно будет писать по образу и подобию этого документа.

Эта проблема возникает не только у технических писателей, но и у писателей-фантастов и инженеров, которые самостоятельно документируют то, что они делают. Менеджер ставит задачу описать архитектуру нового компонента, а мы открываем новый пустой документ и не знаем, с чего начать.

Это большая проблема, поскольку подсознательно у нас формируется достаточно высокий барьер входа в эту деятельность.

Что, в свою очередь, порождает прокрастинацию: «Я не знаю, как начать это дело, поэтому отложу его до завтра, или послезавтра, или послезавтра, когда выполню все дела».

другие задачи проекта».

То есть никогда.

А прокрастинация, скорее всего, и есть та самая причина, по которой вы не пишете документацию.

Лучший способ с этим справиться — предоставить примеры и шаблоны готовой документации и не забыть все это обернуть в процессы.

Примеры и шаблоны документации — лучший способ борьбы с промедлением с документацией.

А также настроенные процессы работы с документацией.

Проблема №3: люди неохотно читают документацию

Читать документацию (или читать что-либо вообще) сложно.

Если вы ищете что-то в огромном корпоративном Confluence с 20 тысячами страниц и получаете 300 результатов по вашему поисковому запросу, то, скорее всего, вы начнете грустить.

Потому что вы понимаете, что релевантность этих страниц неясна, и вам нужно прочитать хотя бы первые 2 страницы результатов поиска, пролистывая каждый из этих документов.

Однако нет никакой гарантии, что вы найдете то, что ищете.

И, скорее всего, вы закроете Confluence и пойдете за информацией к коллеге.

То же самое происходит, когда вам приходится просматривать 200-страничный PDF-файл, чтобы найти ответ на небольшой вопрос.

Есть большая вероятность, что через пять минут вы закроете документ и напишете кому-нибудь в Slack.

Высокий барьер для доступа к чтению документации приводит к прокрастинации.

И общение переходит на голосовые сообщения в WhatsApp.

Сделайте чтение дешевым

Если вашу документацию сложно читать, люди реализуют каналы связи по-другому.

Сделайте документацию если не приятной, то хотя бы дешевой для чтения.

Самое первое, о чем стоит подумать, это единый портал документации с целостной структурой .

Ваша документация не должна быть разбросана по Google Docs, Confluence, Dropbox и электронной почте.

Пусть это будет в одном месте, например в Confluence, где единая гармоничная структура разделов и подразделов, соответствующая декомпозиции вашей предметной области.

Человек, который туда зайдет, будет знать: скорее всего, он найдет то, что ищет, и структура ему в этом поможет. Во-вторых, это поможет вам хорошо структурированный текст, а также грамотный и понятный язык .

Хорошо представленная информация с хорошей структурой побудит людей прочитать документ до конца.

Листы текста без разделения на главы и даже абзацы, с орфографическими ошибками и трехэтажными канцелярскими товарами, скорее всего, остановят чтение где-то на середине и перейдут на усвоение информации устно.

Найдите корпоративного библиотекаря

Мы называем ее «корпоративным библиотекарем».

Это какой-то владелец документации, но не в том смысле, что он всю ее написал или прочитал.

Нет, он просто знает общую карту всей документации, которая есть в проекте и где она находится.

Точно так же, как библиотекарь в обычной библиотеке вряд ли сам прочитает в ней все книги, но он может подсказать вам, в какой книге (или хотя бы на какой полке) вы сможете найти то, что вам нужно.

Поддерживая организованность Confluence, он может реструктурировать структуру в соответствии с тематикой проекта, отсекая старые и устаревшие статьи и напоминая автору статьи пятилетней давности, чтобы тот вовремя ее обновил.

Библиотекарь также может указать автору нового документа, куда его поместить.

Это очень важно, поскольку таким образом можно снизить затраты на написание документов, сообщая разработчикам, к какому разделу относится то, что они написали, тем самым снижая барьер для входа в написание документации.

Вы можете просто отправить статью библиотекарю, и он сам разместит ее там, где нужно.

Проблема № 4: Документация неполная, неточная и устаревшая.

Если вы забыли обновить документацию, значит, вы не учли это в своих процессах разработки.

Если документация не является полной или точной, то вы, вероятно, не очень хорошо проверяете ее качество или не очень четко определяете задачу.

Вам необходимо тщательно продумать, как выглядят процессы разработки и сопровождения документации.

Но прежде чем приступить к их формированию, задайте себе два вопроса: Кому мы пишем и почему?

Кому?

Вы уверены, что с другой стороны есть только одна заинтересованная сторона? Может их несколько и они разные? Если вы думаете, что пишете документацию для разработчиков (например, для пользователей вашего API), то вы, скорее всего, обнаружите, что существует несколько типов пользователей API, и документацию следует писать для каждого типа.

Они могут отличаться, например, уровнем знания вашей предметной области или уровнем профессионального опыта.

Что читатель уже знает о предметной области? Знает ли он, что представляет собой ваш продукт, какие в нем бизнес-процессы? Или, может быть, это нужно объяснить? Или есть читатели вашего документа, которые знают это, а есть те, кто этого не знает? Вам необходимо писать документацию с учетом этого.

Чего он не знает? Есть ли вещи, которые обязательно нужно объяснить? А может, есть что-то, что не нужно объяснять? И не стоит тратить время на документирование API, объясняя читателю, что такое HTTP или каковы принципы REST? А может быть, иногда такие вещи нужно объяснять?

За что?

С какой проблемой сталкивается читатель? Почему принимающая сторона вообще нас слушает? Что ей нужно от этого акта общения? В нашем примере с API, что читатели API хотят знать об API? Структура методов или свойства каждого метода? А может быть, читателю это пока не интересно, но он хочет знать бизнес-цель API, что он может с этим API делать? Или он хочет научиться реализовывать типичные сценарии, которые он ожидает от вашего продукта? И вообще, можно ли с помощью вашего API реализовать те сценарии, которые он хочет? Совсем не факт, что стандартный справочник методов ответит на эти вопросы.

Вероятно, вам нужно написать несколько вводных статей или руководств.

Кто нам поможет?

• Помощь в формировании процессов вокруг документации.

• Помощь в создании шаблонов, примеров и рекомендаций.

• Играя роль библиотекаря, который поможет найти существующую документацию и положить в архив новую.

• Подбор инструментов для разработки и хранения документации.

Хорошая новость: на рынке есть люди, которые по определению занимаются именно этой деятельностью! Это технические писатели.

Технический писатель

Опытный технический писатель, помимо написания документации, может помочь вам создать процесс документирования, чтобы на выходе была документация как артефакт. Но с тех пор он не создает процессы, а помогает их создавать , то скорее всего он не будет их реализовывать в одиночку.

Потому что ему нужен достаточно сильный административный рычаг для создания новых процессов и изменения существующих — менеджеров-союзников, которые внедряют и меняют процессы по его рекомендации.

По нашему опыту, многие компании говорят: «Мы понимаем, что нам нужен технический писатель, но не возьмем его.

Потому что он не знает, что именно писать — он не программист. Он будет просто секретарем, который следит за нашими разработчиками и записывает для них слово в слово то, что они говорят. За что? Тогда нам лучше написать это самим».

Короткий ответ: нет. Технический писатель, особенно с базовым ИТ-образованием, сможет быстро разобраться в вашей предметной области и говорить с разработчиками на одном языке, потому что его профессия - быстро понимать все новое .

Но в то же время у технического писателя действительно есть режим «не пиши все сам».

Технический писатель может:

• Создавайте шаблоны и рекомендации — и отойдите в сторону, а ваши разработчики будут писать дальше.

• Редактируйте и исправляйте существующие документы, чтобы написанное разработчиками было легко читаться и не содержало ошибок.

• Займитесь написанием призраков.

  — создать полноценный документ на основе весьма расплывчатых набросков разработчика на салфетке или на доске (возможно, после сбора дополнительной информации в устном общении).

Технический писатель с многолетним опытом, сильным техническим бэкграундом и IT-образованием, скорее всего, сможет настроить за вас все необходимые процессы или окажет в этом большую помощь.

Во-вторых, внутри вашей команды может вырасти технический писатель — из разработчика, аналитика или менеджера.

Скорее всего, в вашей команде инженеров есть люди, которые думают о документации немного больше, чем все остальные.

Им не хватает эффективного взаимодействия между заинтересованными сторонами, и они хотят, чтобы оно осуществлялось лучше.

Если ситуация позволяет, то пусть они станут теми самыми корпоративными библиотекарями или техническими писателями.

Технический писатель может в конечном итоге вырасти в менеджера знаний, поскольку процесс управления документацией является неотъемлемой частью, прямой частью процесса управления знаниями.

И, конечно же, вы можете нанять внешних консультантов, например, у нас по адресу documentat.io .

Мы настроили подобные штуки не в одной компании и поможем вам с настройкой процессов, разработкой шаблонов, методических рекомендаций и приведением в порядок базы знаний.

Или просто дайте нам часть задач по написанию документации в формате аутсорс/аутстафф.

Давайте подведем итоги

• Документация — это способ общения между участниками проекта.

  Они, конечно, могут переписываться в Slack или обмениваться голосовыми сообщениями в WhatsApp, но лучше делать то же самое через документацию.

• Относитесь к документации как к процессу и как к артефакту.

  Если вы относитесь к документации по-другому, вы не будете относиться к ней никак; вы не создадите его сами.

  Если нет четких требований к артефактам проектирования и процессам вокруг них, вы не получите на выходе ничего конкретного.

• Промедление мешает чтению и написанию документации.

  Уменьшите барьеры для чтения и создания документации, устраните промедление с документацией.

  Если документацию трудно читать, люди не будут ее читать.

  Если сложно писать и непонятно куда разместить, то не напишут.

• Наймите или наймите корпоративного библиотекаря — человека, который заботится о документации и поможет привести ее в порядок.

Конференция Конференция Знаний 2022 пройдет 21-22 марта в Москве.

Мы поговорим об адаптации сотрудников, сохранении знаний внутри компании и личном наставничестве.

Все будет на том же сайте, что и конференция.

Фонд TeamLead Conf 2022 .

Расписание и тезисы докладов уже готовы.

До следующего повышения цен осталось пять дней.

Но вы можете забронировать билеты по текущей цене и выкупить их позже.

• Раскрытие Секретов Успешных Сайтов Электронной Коммерции Volusion

  19 Oct, 24

• Компания По Тестированию Программного Обеспечения

  19 Oct, 24

• Apple Назвала Лучшие Приложения 2015 Года В Российском Сегменте App Store

  19 Oct, 24

• Кто Шьет Трусики Мальчикам? Ну Конечно Не Пилот

  19 Oct, 24

• Что Нового В Flash Player 10.1

  19 Oct, 24

• Массивы, Коллекции: Алгоритмический Минимум

  19 Oct, 24

• Greasemonkey: Облако Популярных Хабратегов При Добавлении Хабратопика

  19 Oct, 24

• Как Просмотреть Документы Онлайн

  19 Oct, 24

• Методы Атрибуции В Популярных Трекерах: Сопоставление Идентификаторов Устройств, Реферер Установки И Отпечаток Пальца.

  19 Oct, 24

• Пользователи Android Заплатят За Слова, Nintendo Выпустит Приложение Для Ios, Rovio Выпустит Книгу — И Другие Новости Недели Для Мобильного Разработчика

  19 Oct, 24