Edit me

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

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

В конце раздела есть короткий опрос для сбора фидбека.

Введение

Если вы не знакомы со Scrum, попробуйте сначала ознакомиться с методологией, прежде чем читать этот раздел. Начните с чтения руководства Scrum. Если вы предпочитаете книжную версию, см. Scrum: The art of doing twice the work in half the time. Это руководство к подходу (небольшая книга).

Подключаемся к Scrum разработки, или создаем свой Scrum

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

Существует несколько преимуществ присоединения к готовому процессу:

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

Помимо преимуществ такого подхода есть и отрицательные моменты:

  • еcли тех. писатель является временным ресурсом в проекте, с продолжительностью работы около месяца или около того, то, вероятно, нет смысла присоединяться к инженерному Scrum. Там слишком много адаптации, знакомство с процессом и многое другое;
  • если Scrum работает плохо, например, ежедневные встречи длятся более 30 минут, и есть несколько scrum-команд, с которыми нужно работать, все это убивает время, истощает пропускную способность, не давая ничего взамен;
  • скорее всего, у тех. писателя будет несколько проектов одновременно. Если нужно изменить свой подход к каждому из них, используя разные варианты Scrum, то собственный рабочий процесс и методология могут почувствовать себя немного разрозненными. Например, если каждый подход рассчитывает все по-разному, имеет разную продолжительность спринта и другие вариации, такое несоответствие своей методологии может быть утомительным;
  • команда инженеров хочет, чтобы тех. писатель присутствовал на всех их встречах Scrum, но не станет относиться к нему как к полноправному участнику Scrum (например, без задач, и т.д.), стоит задуматься о создании собственном Scrum-процессе.

Адаптация Scrum-процессов для создания документации

Если нет смысла присоединяться к инженерному процессу методологии Scrum, можно создать свой собственный процесс. Адаптированный Томом Джонсоном процесс управления документации по методологии Scrum включает в себя следующие шаги:

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

  3. Разделение работы над документацией на тикеты (задачи). Из плана документа создаются тикеты (например, вопросы JIRA), связанные с работой. Тикеты должны примерно обозначить основные задачи для каждого проекта. Тикеты не обязательно должны быть исчерпывающими с самого начала, но они должны дать представление о необходимой работе. Кроме того, не нужно регистрировать все тикеты с самого начала, так как они, скорее всего, окажутся в очереди и станут устаревшими, прежде чем вы даже начнете над ними работать. Основная идея состоит в том, чтобы упростить сложные задачи, разделив работу на небольшие задачи.

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

  4. Оценка веса пунктов для каждого тикета. Каждый пункт оценки сообщают о сложности проекта. Бывает, что каждая команда немного различается в оценке задач. Можно сделать такую систему баллов: полный рабочий день - 2 балла; полдня или меньше - 1 балл. Можно разбивать свои тикеты не более чем на 5 баллов, чтобы показать прогресс и чувствовать окончание работы. Даже для коротких исправлений, которые занимают 10 минут, равно записываю метку для этого. (Более гибкое взвешивание меток обычно не рекомендуется в гибкой методологии.) Оценка нужна, чтобы понимали все, является ли задача сложной или простой.
  5. Разбивка тикетов на двухнедельные спринты. Тикеты должны быть распределены по спринтам. Каждый спринт обычно длится две недели (но может быть разной продолжительности). Для каждого спринта общее усилие каждого писателя должно составлять количество баллов, которые можно выполнить за этот двухнедельный период. Эта скорость прохождения меток называется «скоростью». Это число основано на предыдущих расчетах скорости, поэтому сначала нужно понять свою скорость, что возможно только после нескольких спринтов. Расчет и передача информации о скорости важны для того, чтобы знать, правильно ли тех. писатель укомплектован для выполнения работы с учетом сроков релизов.

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

    При Scrum-подходе к документации чрезвычайно сложно поддерживать план спринта. Различные команды могут иметь непосредственные потребности в быстрых обновлениях. Такие быстрые обновления могут занимать полдня работы или меньше, или могут даже включать исправление опечатки. Быстрые задачи добавляются к основным, динамичным способом к спринту по мере необходимости. Однако, если кто-то подходит со значительной документацией, стоит отложить ее на следующий спринт (который, вероятно, будет через две недели). Люди не ожидают, что можно все бросить и сразу же начать работать над большим проектом. Поэтому, получая информацию о добавлении проекта на предстоящий спринт, они обычно успокаиваются и получают заверение, что их работа запланирована , даже если в настоящее время ничего не делается.

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

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

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

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

    a) Ревью командой разработчиков документации Команда разработчиков документации - это технические писатели, создающих контент. Проверяем все инструкции до конца, проходя каждый шаг. Проверка может включать разработку тестового приложения или другого примера кода. b) Ревью продуктовой командой В состав группы входят разработчики, написавшие код продукта, и менеджеры продукта. Они должны проверить точность и полноту документации. c) Ревью полевыми инженерами, бизнес-разработкой и поддержкой Можно увеличить круг обзора, чтобы включить дополнительные группы и заинтересованные в документации стороны. Передаем документацию этим группам для ознакомления, а затем назначаем встречу для сбора отзывов.

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

    d) Ревью с юр.отделом Если у документации есть какие-либо “флажки”, которые могут вызвать проблемы с юристами, нужно передать документацию группе своих юристов для проверки. e) бета-ревью партнерами Можно сделать бета-ревью документации крупных проектов до ее публикации. Как правило, в этом могут участвовать полевые инженеры и партнер-заказчики.

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

    f) Сбор обратной связи после релиза После публикации документации можно добавить кнопку Отзыв прямо в документацию, чтобы постоянно получать дополнительные отзывы от клиентов. Такая входящая обратная связь накапливается и может не содержать значимой или действенной информации, но клиенты должны иметь какой-то способ ретрансляции своей обратной связи. Техническому писателю стоит знать, есть ли какие-то серьезные проблемы с документами, чтобы их исправить.

Заключение

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

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

Дополнительные материалы

Небольшой опрос

Для сбора фидбека о данном разделе автор курса создал небольшой опрос. Результаты опроса можно посмотреть по ссылке