Как писать документацию к проекту

Пишем техническую документацию: руководство для непрофессионала

Осенью 2016 года нам с коллегой поручили улучшить документацию и контент в моей бывшей компании. Мы потратили год на все виды документации: справочник по API, руководства, учебные пособия, сообщения в блогах. До этого я 5 лет писала доки, но официально не обучалась этому. Но и неопытной меня нельзя назвать: кроме документирования API для проектов и стартапа, я ещё преподавала Python Flask на семинарах во время учёбы на последних курсах в университете. Но сейчас выпала возможность сосредоточиться только на любимом деле: помогать специалистам всех уровней через техническую документацию.

В этом году я многому научилась в сообществе Write The Docs, у других провайдеров API, а также методом проб и ошибок. В прошлом году я поделилась опытом в докладе «Что мне хотелось бы знать о написании документации» на конференции API Strategy and Practice в Портленде. Эта статья — обзор полученных знаний.

Как люди на самом деле читают документацию?

«Нация содрогается от большого фрагмента слитного текста», фото The Onion

Знаете это чувство, как на картинке? Так бывает. Может и не физически, но, скорее всего, люди содрогаются умственно. Меня постоянно мучала мысль, что люди не будут читать мои тексты, если я не оформлю их легко усваиваемым способом. Чёрт возьми, такое может произойти даже с этой статьёй.

В исследовании направления взгляда Neilson Norman Group в 2006 году 232 пользователя просмотрели тысячи веб-страниц. Оказалось, что пользователи обычно смотрят на страницы по F-шаблону:

1. «Сначала читают в горизонтальном направлении, как правило, в верхней части области с контентом. Это верхний элемент фигуры F».
2. «Затем немного перемещаются вниз по странице — и совершают второе горизонтальное движение, которое обычно охватывает более короткую область, чем предыдущее. Этот дополнительный элемент образует средний элемент фигуры F».
3. «Наконец, пользователи сканируют левую сторону контента по вертикали. Иногда это медленное и систематическое сканирование, которое отображается в виде сплошной полосы на теплокарте. Иногда движение более быстрое, образующее пятна на теплокарте. Это последний вертикальный элемент в фигуре F».

Теплокарты Nielsen Norman Group

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

Важно отметить, что F-шаблон мешает пользователям, но хорошее позиционирование контента помогает предотвратить F-сканирование.

Каковы конкретные последствия для документации?

• В первых двух абзацах следует указать самую важную информацию
• Критически важны первые 3−5 слов
• Заголовки, абзацы и маркированные списки с информативными словами
• Изменения шрифта (размер, ссылки, выделения жирным и т. д.) могут быть необходимы, чтобы удержать внимание читателя

Так как структурировать контент на странице?

• Предотвратите сканирование: убедитесь в выделении информации, которая нужна читателю
• Одна мысль на абзац. Если их несколько, разбейте абзац
• Пользователи пропускают всё, что похоже на баннеры, поэтому будьте осторожны с иллюстрациями
• Не расширяйте слишком сильно колонку с текстом: оптимально 65−90 символов

Кроме того, у абзацев есть своя специфика. Подобно слитному тексту The Onion, когда вы читаете много абзацев, можно пропустить суть. Тогда зачем использовать их так часто? Давайте проведём эксперимент из документации Keen IO:

Быстро прочитайте это:

У наборов событий может быть практически любое название, но есть несколько правил: в названии должно быть не более 64 знаков. Оно должно содержать только символы ASCII. Оно не может быть значением null.

Теперь быстро прочитайте это:

У наборов событий может быть практически любое название, но есть несколько правил:

• В названии должно быть не более 64 знаков
• Оно должно содержать только символы ASCII
• Оно не может быть значением null

Позже мы подробнее обсудим вёрстку документации и навигацию по ней.

Примеры кода

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

Контекст в примере кода важен для успеха разработчика. Разработчики любят быстро копировать и вставлять. Вот пример с Keen IO API:

Разработчик быстро копирует и вставляет этот код. И…

Во-первых, как они вообще запускают файл? Вероятно, как node file_name.js , но этого нет в коде. Можно было бы указать в комментарии вверху.

Хорошо, они запустили его и… ReferenceError: Keen is not defined . 🙁 Клиент Keen не инициировался, в верхней части нет оператора import или require, и он работает только после установки библиотеки npm.

Пользователь всё починил и запустил ещё раз… Угадайте?! Ещё одна ошибка! your_project_id и your_write_key отсутствуют.

Всё это можно было бы сделать более очевидным.

Вот пример из документации Twilio, которая предоставляет хороший контекст для конечного пользователя:

Скриншот из документации библиотеки Twilio Node Helper

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

Копипаст багов

Поскольку у нас в документации много примеров кода, успешный копипаст — довольно важное свойство. Вот два примера того, где это не соблюдается:

Кажется довольно безобидным, верно? Подумайте ещё раз, что происходит, когда вы копируете и вставляете это в командную строку? Вы, скорее всего, получите:

Распространённая ошибка. Либо вы хотите, чтобы команда выглядела как в командной строке, либо вы случайно её скопируете. Я бы рекомендовала отказаться от $ . Ещё можно найти способ запретить копипаст этого символа, чтобы ошибка не раздражала пользователей.

Более свежий пример: вы проверяли, насколько легко выделить код, который пользователь хочет скопировать?

Келси Хайтауэр изо всех сил пытался скопировать образец кода из StackOverflow на презентации Google Cloud Next.

In a LIVE DEMO, watch @kelseyhightower build a weather application from zero. Starting from the database up to the end point: https://t.co/XAKsOYSHZq pic.twitter.com/1iuHGlVRnR

— Google Cloud Platform (@GCPcloud) July 26, 2018

«Хорошие программисты копируют, великие программисты вставляют»

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

«Вот и всё!»

«Вот и всё!» Фраза кажется довольно безобидной вне контекста, но представьте, как воспринимаются определённые слова вроде «легко», «просто», «тривиально» и «несложно», когда у вас проблемы — не здорово! Когда человек застрял, пытаясь заставить API работать, такая фраза подвергает сомнению его интеллект и заставляет задать вопрос: «Значит, я глупый?» Это деморализует.

Чрезмерное упрощение

Упрощение встречается повсеместно. Оно наиболее распространено среди новичков в написании документации. Зачастую авторы документации — одновременно и разработчики системы, поэтому некоторые вещи им кажутся «лёгкими». Но ведь они разработали эту функцию, написали для неё код, проверили много, много раз, а потом написали документацию. Когда вы делаете что-то десятки раз, то ясное дело, что это будет «легко» для вас. Но как насчёт того, кто никогда раньше не видел UI или функцию?

Сопереживание

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

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

• Попросите менее опытных участников проекта честно прокомментировать документацию
• Поощряйте менее опытных участников проекта вносить свой вклад или указывать на пункты документации, которые они не понимают
• Создайте окружение, где поощряются вопросы, в том числе такие, какие могут показаться «очевидными» для опытных участников проекта — это поможет заметить «слепые зоны»
• В процессах код-ревью и CI используйте линтеры, чтобы гарантировать эмпатию и дружественность языка для всех пользователей
• Наконец, попросите прокомментировать документацию реальных пользователей, покажите им текст и спросите, всё ли понятно

Сообщения об ошибках как вид документации

Обычно пользователи чаще видят сообщения об ошибках, чем документацию. Как говорит Кейт Восс, «сообщения об ошибках на самом деле представляют собой возможность». Я считаю, что многие разработчики документации упускают эту возможность. Здесь есть место для обучения, установления доверительных отношений и ожиданий пользователей. Прежде всего, вы поможете людям помочь самим себе.

Кейт на сайте Write The Docs рассказывает много полезного о написании сообщений об ошибках. Многое я узнала во время прошлой работы над сообщениями об ошибках API, а также будучи на другой стороне баррикад, получая сообщения об ошибках других API в качестве разработчика.

Кейт говорит, что хорошие сообщения об ошибках построены на трёх принципах:

• Скромность
• Гуманность
• Полезность

Скромность

Сразу нужно извиниться, даже если это не ваша вина. Это я практикую также в службе поддержки.

Гуманность

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

Пример (ошибка кода состояния 401 у Twilio):

Полезность

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

Как писать сообщения об ошибках

Как и в любой другой документации, сначала укажите важную информацию. Это можно сделать, указав сначала объект, затем действие. Пользователь ищет результат, а не как туда добраться. Это полезно, когда пользователи быстро сканируют сообщения об ошибках.

Сообщения об ошибках в документации

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

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

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

Источник: https://www.twilio.com/docs/api/errors

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

Источник: https://www.twilio.com/docs/api/errors

Вы даже можете найти свои сообщения об ошибках в вопросах StackOverflow. Ответьте на них скромно, по-человечески и с пользой. Из-за SEO пользователи часто попадают с вашими сообщениями об ошибках на StackOverflow, а не в реальную документацию.

Выбор слов

У многих слов есть устоявшиеся ментальные модели. Например, такие слова, как «библиотеки», SDK, «обёртки» и «клиенты» уже перегружены и проходят мимо внимания читателя.

В своей лекции «Даже для этой лекции трудно подобрать название» на Write The Docs Рути Бендор говорит, почему выбор правильных слов может быть таким трудным.

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

В такой ситуации как никогда справедлива известная поговорка: «Есть только две трудные задачи в области информатики: инвалидация кеша и придумывание названий». Цитату часто приписывают Филу Карлтону, но сегодня ходит много вариантов этой поговорки. Иногда в конце добавляют «… и ошибка на единицу». Рути считает это демонстрацией, что программное обеспечение в наши дни во многом основано на чужом коде или работе.

Почему же сохраняются плохие названия объектов (или документация)?

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

Мне это ещё напоминает то, что Рути называет ошибкой мышления новичка. Это как сказать «Мне это совершенно ясно. Не понимаю, как кто-то не может этого понять».

Наконец, Рути упоминает ошибку локализации. Например, слово Bing по-китайски означает «больной».

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

Есть ещё случаи, когда мы признаём ошибку, но не можем или не хотим её исправлять, потому что мы…

• Привязаны к ней
• Не находим времени
• Не видим важности
• У нас нет агентства, чтобы её исправить

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

Как правильно подобрать слова?

Для начала рекомендую задать вопрос: какие слова используют ваши пользователи? В разных программистских кругах в ходу разные термины, не пытайтесь использовать другие. Это полезно не только для читателей, но также для поиска и SEO.

В конце концов, всё неизбежно сводится к субъективной оценке. Однако есть несколько принципов, которые стоит учесть. Рути говорит, что плохие названия — это те, что могут:

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

• способствуют внезапному прояснению («вот оно что!»)
• вводят в контекст
• объясняют
• освещают
• оказывают поддержку

Подбирать верные слова трудно. Волшебной формулы не существует. Все пользователи отличаются, как и варианты использования продукта; что работает для одних, может не работать для других. Если бы это было легко, у всех была бы намного лучшая документация. Как говорит Рути разработчикам: «Написание программ — это упражнение в придумывании названий. Смиритесь с этим». И если вы пишете документацию для чужой программы, «сообщите разработчику, если его названия не попадают в цель».

ЕСКД 2020: как оформлять документацию по-новому?

С 1 июля 2020 года действуют новые требования к оформлению текстовой документации. Цель нового свода правил — стандартизировать форму заполнения конструкторской документации. Структура и состав текстов в сфере строительства, машино- и приборостроения должны подчиняться единым нормам.

Два нововведения предусмотрены приказом Федерального агентства по техническому регулированию и метрологии № 175-ст от 29.04.2019.

• ГОСТ 2.105-95 утрачивает силу в качестве национального стандарта, но сохраняет действие в качестве межгосударственного;
• ГОСТ Р 2.105-2019 признают национальным.

Обратите внимание и на ряд других ГОСТов, принятых в данной сфере:

• ГОСТ Р 2.106-2019 «Единая система конструкторской документации. Текстовые документы», утверждён приказом Росстандарта от 29.04.2019
• ГОСТ Р 2.601-2019 «Единая система конструкторской документации. Эксплуатационные документы», утверждён приказом Росстандарта от 29.04.2019
• ГОСТ Р 2.711-2019 «Единая система конструкторской документации. Схема деления изделия на составные части», утверждён приказом Росстандарта от 29.04.2019
• ГОСТ Р 2.610-2019 «Единая система конструкторской документации. Правила выполнения эксплуатационных документов», утверждён приказом Росстандарта от 29.04.2019

Напомним, требования единой системы конструкторской документации (ЕСКД) в РФ считаются добровольными. И если вы выполняете заказ, можно руководствоваться стандартами, выставленными заказчиком. Если документация оформляется для российского рынка, стоит пользоваться правилами оформления из национального свода.

Продолжить работу по следует, если вы готовите бумаги для партнеров из ЕАЭС. Когда документами пользуются компании и из России, и из других стран, укажите наименование стандарта, который был использован при их подготовке.

Как оформлять документацию: 4 способа

Документы можно подготовить как в электронном, так и в рукописном виде. Для каждого варианта есть свои ГОСТы.

1. Машинописным способом в соответствии с Межгосударственный стандарт. Репрография. Микрография. Документы для микрофильмирования. Общие требования и нормы (введен в действие Постановлением Госстандарта России от 26.02.2004
2. Рукописным методом, используя положения Межгосударственный стандарт. Единая система конструкторской документации. Шрифты чертежные (утверждён Постановлением Госстандарта СССР от 28.03.1981 № 1562).
3. Применяя ЭВМ, согласно Межгосударственный стандарт. Единая система конструкторской документации. Общие требования к выполнению конструкторских и технологических документов на печатающих и графических устройствах вывода ЭВМ (утверждён Постановлением Госстандарта СССР от 28.11.1988 № 3843).
4. На электронных носителях информации.

Обратите внимание, что текстовые документы электронных (ТДЭ), согласно правилам, допускается готовить с использованием стандартизованных информационных моделей программ. Данные будут либо сгенерированы автоматически с помощью специализированных программных средств из заранее подготовленных фрагментов, либо набираются вручную.

Техническое оформление документов: общие требования

Правила ГОСТ к оформлению тестовых документов отличаются. Всё зависит от того, кто утверждал стандарт (Таблица 1).

Таблица 1. Разница и сходство редакций ГОСТ.

Высота символов — не менее 2,5 мм.

• Шрифт Times New Roman или Arial размером 14 для основного текста и размером 12 для приложений, примечаний, сносок и примеров;
• допускается использование шрифта размером 13 и 11 для основного текста и размером 12 и 10 для приложений, примечаний, сносок и примеров соответственно.

Расстояние между боковыми линиями формы и текстом должно составлять минимум 3 мм.

Абзац начинается с красной строки, минимальный отступ —

Абзацы начинается с отступа, равного

От нижней и верхней границ следует отступать не менее 10 мм.

Интервал между строками — не менее 8 мм.

• Текст оформляют с использованием полуторного межстрочного интервала;
• допускается использование двойного межстрочного интервала.

• Расстояние между заголовком и текстом при выполнении документа машинописным способом равно 3, 4 интервалам, при выполнении рукописным способом — 15 мм;
• расстояние между заголовками раздела и подраздела — 2 интервала, при выполнении рукописным способом — 8 мм.

• Расстояние между заголовком и текстом, между заголовками раздела и подраздела — не менее 4 высот шрифта, которым набран основной текст. Расстояние между строками заголовков подразделов и пунктов принимают таким же, как в тексте;
• при выполнении машинописным способом интервал равен 3 или 4 интервалам, при выполнении рукописным способом — не менее 15 мм.

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

Нумерацию документов ЕСКД позволяет сделать как сквозной, так и отдельной для каждого раздела.

Чего делать нельзя: 9 запретов

В требованиях к текстовым документам содержится ряд запретов. Например, требования единой системы конструкторской документации (ЕСКД 2020) года запрещают:

1. Указывать индексы стандартов без обозначения присвоенного им регистрационного номера.
2. Писать математические знаки без числового сопровождения.
3. Ставить знак минус для обозначения отрицательных чисел.
4. Перечеркивать круг в качестве обозначения диаметра.

В самом тексте недопустимо применять:

1. Сокращения слов, кроме установленных правилами русской орфографии, соответствующими государственными стандартами, а также в данном документе.
2. Обороты разговорной речи, техницизмы, профессионализмы.
3. Для одного и того же понятия различные научно-технические термины, близкие по смыслу (синонимы), иностранные слова и термины при наличии равнозначных слов и терминов в русском языке.
4. Произвольные словообразования.

К физическим величинам тоже есть требования:

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

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

Рекомендуем

Курс предусматривает изучение требований законодательства о техническом регулировании и стандартизации, освоение нормативных документов ЕСКД и ЕСТД, освоение основ проведения нормоконтроля конструкторской и технологической документации.

Документальное оформление бизнес-процессов в проектах по автоматизации

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

Структура проектной документации проекта 1С и место бизнес-процессов в ней

Для начала приведу общие принципы разработки документации

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

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

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

При описании реализуемого продукта обычно есть два ключевых акцента информации – функциональная и бизнес-структура. Соответственно, акцент может делаться на:

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

Либо на бизнес-процессы – изначально оторванные или частично оторванные от конечного продукта процессы компании.

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

Подходы к декомпозиции бизнес-процессов

Расскажу, как мы описываем процессы, постараюсь объяснить свою точку зрения, как это делать наиболее эффективно.

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

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

Самый первый уровень – это группы процессов. Здесь могут быть:

либо группы процессов, ориентированные на конкретные виды деятельности;

либо группы процессов, ориентированные на управляющую компанию – на управление инвестициями и централизованные контроли.

Второй уровень процессов – это группы процессов, разделяющие тот или иной конкретный вид деятельности на бизнес-функции. Когда вы пытаетесь отрисовать дерево бизнес-процессов в компании или хотите составить план интервью, вы можете запросить структуру предприятия и всех его компаний, и на основании этого проанализировать, какие там есть подразделения и как они называются. Зная состав подразделений, вы, как минимум, сможете составить первичное представление о том, какие в компании есть бизнес-функции. В основе второго уровня описания декомпозиции процессов должны лежать как раз-таки виды бизнес-функций, обычно в привязке к подразделениям.

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

Нотации, которые я считаю наиболее эффективными при описании бизнес-процессов.

Для описания процессов уровня 3 и ниже (для описания подпроцессов конкретных бизнес-функций) я считаю наиболее подходящими нотации BPMN или EPC. Лично я предпочитаю использовать для этой цели BPMN, потому что он достаточно информативный и понятный – его и бизнес понимает, и в принципе, в нем достаточно насыщена логика, чтобы подробно описать бизнес-процесс даже неопытному специалисту. Но это исключительно мое мнение – я знаю, что есть идеологи других нотаций.

А нотацию IDEF0, я считаю, удобно использовать для верхнеуровневых процессов – для уровня 1 и 2, потому что в том же BPMN не получится отрисовать всю сложность взаимосвязей этих групп процессов, либо придется ее как-то избыточно детализировать, что не приветствуется. А в IDEF можно сделать много стрелок.

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

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

На слайде показан пример, как мы описываем декомпозицию процессов.

А здесь приведена безличная схема описания бизнес-процесса в BPMN.

Подходы к описанию бизнес-процесса

Поговорим про информацию, которая детализирует пояснение к схеме.

Обязательно выделяйте атрибуты бизнес-процесса.

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

Владелец – это какое-то подразделение или даже какая-то роль, если вы описываете бизнес-процесс для конкретной компании.

Старт – это событие или группа событий, в результате которых процесс запускается.

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

Окончание – это событие или группа событий, в результате которых процесс завершается, и продукт – готовится или не готовится.

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

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

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

Также у шага есть атрибуты:

Описание бизнес-действия;

Исполнитель – роль, выполняющая действие;

Входящая информация;

Исходящая информация;

Хозяйственная операция;

Бизнес-требование;

Функциональные требования;

Объекты системы;

Действие в системе;

Требуемая модификация и т.д.

Это – те атрибуты, с которыми мы работаем. Причем, здесь не весь список.

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

На слайде я привел пример таблицы с описанием бизнес-процесса в том виде, как мы ее заполняем в ТЗ. Причем, здесь видны не все, а только некоторые колонки.

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

Важно помнить, что, если мы внедряем не тиражируемые решения, а адаптируем продукт под конкретный бизнес-процесс компании, подробное описание бизнес-процесса в ТЗ нельзя игнорировать.

Что дает описание бизнес-процесса

Что дает описанный подход к описанию бизнес-процессов?

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

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

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

Перечень объектов системы, их полей и макеты печатных форм – составляется на основании описания действий системы.

Перечень требуемых модификаций.

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

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

Данная статья написана по итогам доклада (видео), прочитанного на онлайн-митапе "Бизнес-аналитик. Роль в команде, компетенции, инструментарий". Больше статей можно прочитать здесь.

Как писать документацию к проекту

Проектная документация делает процесс согласований проще для обеих сторон. Вы сэкономите свое время на объяснении терминов, а клиенту не нужно будет вычитывать десятки страниц ТЗ. Визуализация на этапе согласования помогает:

• cнизить риски в ходе самого проекта. Когда веб-разработка уже будет в активной стадии, вам нужно будет пройти еще несколько этапов утверждения. Если на стадии обсуждения вы придете с заказчиком к консенсусу, то вероятность того, что все придется переделывать в середине работы будет сведена к минимуму;
• упростить и декомпозировать комплексные задачи. Управление проектом с помощью фасилитации — одно из ключевых преимуществ проектной документации. Результат становится наглядным, поэтому и согласование с клиентом проходит легче и команда более четко понимает стоящие перед ней задачи и ожидаемый итог работы;
• выстроить нормальные отношения с клиентом. Уровень взаимопонимания с заказчиком напрямую влияет на успешность вашего проекта, скорость и качество его реализации. Общение на равных за счет упрощения и визуализации поможет вам на следующих этапах разработки быть более мобильными в принятии решений и одновременно даст больше возможностей для дополнительных продаж, так как вы будете лучше понимать, что именно необходимо для функционирования ресурса.

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

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

1. Хочет ли клиент добавить на сайт такую же функцию?

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

2. Нужна ли бизнесу клиента данная функция?

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

3. Насколько сильно добавление этой функции повлияет на смету и сроки проекта?

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

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

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

Схематичная визуализация результатов асессорского аудита

Кто входит в команду разработки проектной документации

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

1. Ведет всю коммуникацию с клиентом. Даже если вы привлекаете других специалистов для разработки проектной документации, постарайтесь сделать так, чтобы напрямую с заказчиком общался только кто-то один. Так клиенту не придется запоминать несколько имен, дублировать информацию и объяснять свои пожелания по нескольку раз. Проектный менеджер коммуницирует с клиентом, записывает ключевые идеи и передает их своей команде.
2. Контролирует деятельность сотрудников, работающих над проектом.Проектный менеджер отвечает за то, чтобы все было сделано в срок, все комментарии отработаны, а обратная связь отправлена. В его задачи входит и мониторинг деятельности команды: он выстраивает коммуникацию между специалистами, следит за всеми чатами, отвечает на любые вопросы.
3. Согласовывает все этапы работ. Все специалисты отправляют свои наработки сначала проектному менеджеру, он вносит правки и только после этого отправляет макеты на согласование клиенту.

На сложных проектах еще на этапе первичных согласований к проектному менеджеру подключаются бизнес-аналитик и дизайнер. Бизнес-аналитики начинают свою работу с изучения рынка и анализа текущей ситуации по проекту.

Имейте в виду, что если для визуализации вам нужны только схемы, то не обязательно привлекать дизайнера. Достаточно выбрать интуитивно понятное приложение, где сам аналитик сможет отрисовать простейшие макеты и указать взаимосвязи между объектами. Мы пользуемся общеизвестной платформой Figma для комплексных проектов и Miro, если основная часть работ — простые схематичные изображения.

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

Визуализация структуры сайта

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

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

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