Привет, Хабр! Ранее я писал о том, как можно подружить разработчика и писателя в рамках единого процесса и о подходе Docs-as-code к документированию разработки. Здесь мне бы хотелось поразмышлять, как в условиях agile и постоянного развития одновременно перестраивать документирование под требования других процессов, зачастую не очень предсказуемых, и при этом сохранить максимальную целостность, качество и единообразие документации.
Понятно, когда разрабатывается и постоянно развивается новый продукт, а процессы документирования еще не до конца выстроены, приходится иметь дело с банальнейшим бардаком при подготовке технической документации, который ведет к такому же бардаку при сдаче ее заказчикам. Каждая группа разработки фиксирует документацию так, как считает правильным, но понятия правильности у всех могут быть разные. Приемка же технических документов зависит от позиции и настроения заказчика – лоялен он компании или нет, хочется ему принять все поскорее или наоборот – потянуть резину. Отсюда бывают моменты, когда отвратительного качества сырые материалы принимаются без оговорок, а вполне приличные отвергаются с требованием переделать или доработать их. Для борьбы с этим надо принять ряд простых и понятных для каждого мер: попросту упорядочить процессы на уровне конвенции и закрепить это в инструкциях, обязательных для соблюдения. О том, какие конкретно меры требуются, и пойдет речь.
______________________________
3 меры для борьбы с бардаком в документировании
1. Зафиксировать жизненный цикл документации
Первая и основная мера компании – это внедрение понятного и прозрачного жизненного цикла документации, на каждом этапе которого каждый знает порядок и набор своих действий. Например, при продуктовой разработке ответственность за внедрение новых функций и обновление старых обычно ложится на функционального аналитика, и, соответственно, он должен выступать как минимум источником инициатив по документированию и участвовать в планировании соответствующих задач. Качество текста – ответственность технического редактора, если, конечно, такая роль предусмотрена, и именно он должен быть последним, кто читает текст и одобряет его для публикации или передачи заказчику. Участников процесса может быть сколько угодно, главное обязательно зафиксировать их роли, порядок включения в процесс и ответственность в нормативных документах.
В принципе, ЖЦ документации как явление рассматривался уже столько раз, что говорить о нем немного неуместно – можно просто открыть любую книгу или курс по документированию, ну, или форум техписателей. Ниже смотрите примерную структуру жизненного цикла, составленную на основе различных источников (Рисунок 1).
2. Понять целевую аудиторию и зафиксировать требования к документам для каждой группы читателей
Каждый документ имеет свою целевую аудиторию, причем для разных видов документов эта аудитория также различна. Необходимо четко выделять внутренние документы и документацию для внешнего потребителя, документы сугубо технического назначения и общетехнические материалы для широкого круга пользователей. Для каждого вида должна быть обозначена своя аудитория и свой стиль.
Так, например, документы для внешнего потребителя должны строго соответствовать требованиям языковых и технических стандартов описаний и документации. Внутренние же вполне могут быть оформлены более простым языком – с отступлением от общих требований; главное, чтобы они были впоследствии приняты и поняты в данном сообществе разработчиков – важно правильно выбрать сленг, синтаксические конструкции, структуру и т. п.
3. Разработать фирменный стандарт оформления документов
Да, сейчас можно сказать, что соответствие требованиям норм и стандартов – вещь весьма условная, и большинство организаций и предприятий, если они не принадлежат к категории оборонных, не требуют стопроцентного соответствия документов ГОСТам и другим стандартам. Но порядок то нужен, и с этим никто не поспорит. А ГОСТ – это наиболее упорядоченный свод требований. Да, он часто бывает запутан. Да, он бывает избыточен. Но мы сейчас не говорим о создании документа в соответствии со всеми требованиями по отступам, рамочкам, титулам и т. п. Для самостоятельной компании со своим отделом технических писателей и достаточно большим пакетом проектов и заказчиков просто необходим фирменный стандарт оформления внешних документов, в котором вполне можно предусмотреть основные моменты редакторской политики, графические средства и т. п. А вот в качестве основы для такого фирменного стандарта вполне может выступить отраслевой ГОСТ. Для нас, например, наиболее актуальны ГОСТы 34-й и 19-й серий. Причем, достаточно четко и понятно требования к содержанию и структуре документов прописаны именно в 34-й серии, конкретнее – в РД-50, который сейчас уже недействителен (отменен в 2019 году), но лучшего то ничего не придумали. Так почему бы не взять наиболее рациональные блоки по оформлению и структурированию документов оттуда и не переработать их в фирменную редполитику?
Еще один момент, о котором не стоит забывать, – многие наши заказчики работают (или когда-то работали) строго по обозначенным выше ГОСТам, и часто спрашивают, даже полубессознательно, о соответствии именно этим требованиям. Или же, даже если нет необходимости следовать ГОСТам, заказчикам все равно нужны более или менее четкие критерии для приемки. А где они их возьмут? Да все там же – в ГОСТах. Вот и получается, что даже декларируя отсутствие требований, мы все равно вынуждены им следовать хотя бы в общих чертах. Поверьте, это лучше, чем когда заказчик руководствуется принципом «я художник – я так вижу». Документацию при таком подходе можно сдавать долго и нудно. А уж какие при этом будут понесены потери!
Так почему же не сделать ход сразу и иметь проработанный документ, на основании которого мы можем утверждать, что наша документация соответствует требованиям стандартов? Большинство багов в документации сразу отпадут, снизится нагрузка на техподдержку, и, конечно же, убавится стресса и истерик у аналитиков и писателей. Если у кого-то будут претензии к нашей документации, то мы сможем сказать, что вот именно так рекомендуется делать согласно такому-то ГОСТу, и если у заказчика есть потребность в каком-то другом подходе, то пусть он опишет, где и как этот подход представлен. Мы всегда готовы подкорректировать документацию для него. Это же облегчит работу для всех.
Итак, на основе четких требований к документации и прозрачного жизненного цикла мы можем примирить всех – разработчиков, заказчиков и писателей. Ну или хотя бы снизить градус напряженности при принятии документации на продукты. Заодно это поможет навести порядок в структуре документов. О структуре, пожалуй, стоит написать отдельную статью, и не одну, но здесь в качестве «введения в предмет» давайте хотя бы галопом пробежимся по требованиям к основным документам.
Ремарка: я не буду говорить о сугубо технических документах типа технического задания или техно-рабочего проекта, а также о внутренней документации, которая, как уже отмечалось выше, вполне может оформляться как удобно разработчику, лишь бы команде было понятно.
Требования к структуре документации. Введение в предмет
Структура документации должна быть максимально прозрачной, в принципе, таковой ее и рисуют ГОСТы 34-й серии, которые можно приспособить под нужды компании-разработчика ПО. Можно назвать девять главных документов, необходимых для жизни продукта – приложения, сервиса и т. п.:
Функциональное описание сервиса или приложения с архитектурными схемами и другой информацией.
Файл Readme.
Changelog.
Описание (спецификация) API.
Руководство по развертыванию.
Руководство администратора.
Руководство пользователя.
Руководство программиста (это скорее опция, т. к. требуется только в тех случаях, когда продукт позиционируется как платформа для дальнейшей разработки собственных приложений и сервисов. Наш продукт – платформа ZIIoT – относится к таковым).
Руководство оператора (когда система предусматривает совсем уж простые операции с ПО и не планируется заморачивать народ чтением длинных инструкций).
Формировать перечень документов можно по простейшему алгоритму – смотрите Рис. 2.
Попробуем рассмотреть структуру упомянутых документов и разобраться, что же в них лучше отразить, а чего там быть не должно. Пойдем по порядку.
Функциональное описание
Функциональное описание составляется аналитиком или техническим писателем по заданию аналитика. В него включаются назначение и функции ПО, требования к нему, а также сведения об архитектуре, интерфейсе и процессах интеграции. Этот документ просто необходим при выпуске ПО, которое может масштабироваться и адаптироваться под заказчика, а также на основе которого заказчик может вести собственную разработку.
Обычно в функциональное описание включаются следующие разделы (в соответствии с ГОСТ 19.402-78):
Общие сведения (обозначение и наименование приложения, зависимости и взаимодействующее ПО и сервисы, языки программирования).
Функциональное назначение (назначение программы и сведения о функциональных ограничениях на применение).
Описание логической структуры (информация об архитектуре и интеграции системы, алгоритме программы, структуре программы с описанием функций ее составных частей, связей между ними и т. п.).
Технические средства (требования к компьютерному обеспечению, на котором должно работать ПО).
Вызов и загрузка.
Формат данных на входе и на выходе.
Readme
Разговор о readme обычно вызывает море хейта, т. к. любой разработчик скажет, что его readme идеален – лучше и сделать нельзя. Выработать требования к такому файлу попросту нереально, т. к. каждая команда видит его в свете своей разработки.
Основное требование, которому необходимо следовать, – readme ведется непосредственно участниками разработки и должен содержать основные сведения о проекте, необходимые для его запуска и работы с ним:
Полное наименование приложения/сервиса.
Краткое описание.
Использованные при разработке технологии и кодовая база.
Установка и настройка программы, необходимые переменные и т. п.
Характерные особенности, которые могут проявиться при работе с программой.
Демо (изображения, ссылки на видео, интерактивные демо-ссылки).
Changelog
Журнал изменений или changelog – это файл, в котором содержатся все значимые изменения для каждой версии ПО. Эти изменения упорядочены, расположены в хронологическом порядке и в идеале всегда актуальны. Идеально, если журнал изменений генерируется автоматически. Тогда команде не приходится заморачиваться при каждом изменении в проекте – все они будут автоматически отражены в журнале.
И здесь также можно сформулировать основное требование – выработать соглашение о коммитах, которому будут следовать все команды разработки. Ну не так это сложно, как кажется на первый взгляд.
Описание API
Документация API – это технический документ о том, как использовать API. Чаще всего он генерируется автоматом, но нужны единые правила и требования к формированию спецификаций. Иначе все рискуют получить невнятное или пустое описание, которое не поможет никому.
Руководство по развертыванию
Данный вид документа достаточно специфический и составляется командой системных инженеров. Технический писатель здесь может помочь разве что с оформлением текста более читабельным языком. Наши заказчики обычно хотят видеть в этом документе такие сведения, как:
Возможные (типовые) конфигурации системы.
Пошаговый порядок развертывания каждой типовой конфигурации.
Порядок проверки работоспособности системы, полученной после установки.
Этот список мы и берем в качестве основных требований. Если же эти сведения будут представлены в форме инструкций, то претензий от заказчиков будет значительно меньше.
Руководство администратора
Руководство администратора помогает пользователям, ответственным за администрирование системы, следить за порядком ее работы, управлять доступом к ней, корректировать данные и так далее. По ГОСТу (РД-50), руководство администратора должно включать:
Назначение и порядок использования программного продукта.
Описание общей логики функционирования системы.
Администраторские обязанности и связанные с ними операции.
Регламент выполнения каждой операции (очередность, периодичность, обязательность).
Перечень мероприятий по обслуживанию системы с указанием порядка проведения:
настройка и параметризация;
справочно-нормативные данные;
описание управления учетными записями;
способы назначения прав доступа;
ввод и вывод информации;
описания возможных проблем или неполадок функционирования системы, методов их устранения.
Руководство пользователя
Руководство пользователя предназначено для того, чтобы помочь пользователю самостоятельно работать с ПО. По большому счету, основное требование заключается в том, чтобы в таком руководстве пользователь смог найти максимально полное описание интерфейса, операций, которые он может совершать через него, и проблем со способами их устранения.
Основные разделы руководства пользователя по РД-50:
1) Введение.
2) Назначение и условия применения.
3) Подготовка к работе.
4) Описание операций.
5) Аварийные ситуации.
6) Рекомендации по устранению проблем.
Руководства программиста и оператора
Следует заметить, что для руководств программиста и оператора нет такой уж богатой нормативной базы – каждый заказчик предъявляет к ним свои требования в зависимости от собственных «хотелок» и нужд. Но разрабатывать правила для таких документов все равно нужно. В частности, сейчас мы работаем над руководством программиста, оно, само собой, вызывает много споров и разногласий. В одной из следующих статей поделюсь с вами, к чему мы в результате придем и какие требования сформируем. Особенности руководства оператора мы тоже в перспективе раскроем.
А где же боль и как ее облегчить?
Не все и не всегда готовы принять новую схему работы. Существует достаточно много команд разработки, у которых устоялись иные традиции:
планирование осуществляется стихийно;
писатель не является полноценным участником процесса разработки, а выступает в качестве этакой пишущей машинки;
за качество документа отвечает, в конечном счете, продуктовик, который в общем-то хорошо общается с заказчиком, и документация у него принимается даже не в самом лучшем виде.
Да, такая схема может работать, но только в небольших компаниях с небольшим количеством клиентов. Если же нужно соответствовать условиям рынка, а уж тем более конкурировать с другими вендорами, то необходимо пересматривать свои процессы и подходы, причем, как показывает практика, не один раз, и устанавливать правила игры для всех участников этих процессов.
Казалось бы, это просто – понять и принять необходимость игры по общим для всех правилам. Но по опыту все не так просто и не так быстро. Трудности и медленный темп связаны с тем, о чем я уже говорил в предыдущей публикации, – с боязнью перемен и неготовностью команд разработки перестраиваться на новые рельсы. И здесь стоит вспомнить о создании культуры эксперимента. Под экспериментом понимаем небольшие изменения, не требующие каких-то значительных перестроек, но способные направить процесс к улучшениям (по Эстер Дерби). По сути, все agile-методы построены на идее небольших доработок и изменений, что позволяет в любой момент скорректировать продукт и процесс разработки под меняющиеся реалии. Документирование здесь не исключение. Это живой и подвижный процесс, который тоже должен меняться и улучшаться, не весь сразу, а постепенно – с постепенным вводом новых правил и порядков и их корректированием для приспособления к меняющимся условиям. Эти правила пусть и не застрахуют от всех ошибок, но по меньшей мере сократят их количество. Жить по правилам, даже общего плана, трудно и больно на первом этапе, но это необходимо.
P.S. В этой статье я говорил лишь о верхнеуровневых требованиях, которые должны предъявляться к внешней документации. Конечно, точек зрения на ее форму может быть много, а по отдельным документам так и просто можно писать монографии. Моей целью было сформировать общий вектор нашего движения к упорядоченной документации. В дальнейших же материалах я или мои коллеги попробуем развернуть основные требования и более подробно рассмотреть особенности некоторых видов документов в свете нашего подхода к документированию.
P.P.S. Отдельно хочу отметить, что в данной статье речь идет о формировании документации для «кондовых» технологических предприятий, работающих по ГОСТам. За время написания материала у нас наступило «прозрение», и мы поняли, что организация документации в виде длинных и нудных простыней, уходящих куда-то под стол (за рамки экрана ПК), видимо, не есть лучшее решение, и надо что-то менять в нашей жизни. Мы проработали новую структуру документации, оптимизировав ее в соответствии с требованиями docops и технологических норм, но это уже совсем другая история...