Чем DevOps полезен для вашей документации?
Благодаря… как бы это выразиться… крайне гибкому определению DevOps, есть тьма-тьмущая способов разделить и сгруппировать эти практики. К счастью, в сфере документации мы можем применить упрощенный подход, поскольку наш главный продукт - не код, а проза. И снова я посмотрела, что делают у себя сообщества ПО с открытым кодом и команды документации Red Hat, и попытаюсь сейчас разложить «DevOps для документации» на следующие составляющие:
Некоторые подходы и инструменты, которые я опишу, были с нами годами, другие только начинают набирать обороты в сфере документации. Что приводит меня в восторг - это то, что писатели могут задействовать все знания, навыки и инструменты наших коллег-программистов, чтобы создать быстрый и точный контент для наших нетерпеливых пользователей. А еще это значит, что мы можем проделывать кое-какие крутые штуки с нашим контентом! Единый инструментарийОт контроля версий исходного года, языков разметки и парсеров публикации до непрерывной интеграции и автоматического тестирования - давно миновали дни простого «набрал в редакторе - распечатал в виде книжки». Технологии открытого ПО сыграли решающую роль в продвижении этих усилий, поскольку необходимость быстрой, рациональной, интегрированной документации создала целое семейство инструментов написания и публикации, и они неплохо управляются с кодом, который мы документируем. В наше время в сердцевине большей части документации вы можете найти файлы исходного кода, написанные на одном или более языке разметки из того множества, что есть у нас в распоряжении - например, DocBook XML, Markdown (и его 31 оттенок), AsciiDoc и reStructuredText. Эти текстовые файлы с тэгами обычно хранятся в системе контроля версий Git (при помощи GutHub или GitLab или без таковой), той же самой платформе, которую большинство сообществ открытого ПО, а также Red Hat используют для своего кода. Многие проекты с открытым кодом хранят документацию рядом с кодом или вместе с ним, а некоторые используют интересные трюки, чтобы поток публикаций шел в ногу со сборкой проекта, а создание контента упростилось. К примеру, KDE использует хитрые скрипты, чтобы превратить Wiki-библиотеки в руководства на основе DocBook, - таким образом, вы можете писать при помощи простого Markdown и, по-прежнему, пользоваться надежными возможностями публикации DocBook. NixOS использует менеджеров упаковки Nix, чтобы упаковать документацию Nix, а GitHub использует GitHub, чтобы документировать GitHub. Весьма описательно! В Red Hat и других крупных компаниях, где нужно документировать много продуктов при помощи разных, иногда пререкающихся, писательских команд, нам нужны некие дополнительные проверки и сверки, чтобы убедиться, что наша документация на всех стадиях разработки остается в здравом уме. К счастью, у нас есть любящие свое дело и талантливые люди с творческим, вдохновленным открытым ПО, подходом, которые не только улучшили наши внутренние процессы, но также помогли нам совместить изрядное количество инструментов с теми, которые используются в проектах с открытым ПО, которые мы поддерживаем. Вот так мы и пришли к непрерывной развертываемой интеграции в Jenkins (у нас есть непрерывная интеграция для документов!), где при каждом коммите не только проверяется вся библиотека документации по продукту на наличие битых ссылок и других ошибок, но также производится HTML и PDF, которые мы можем просмотреть через пользовательский интерфейс Jenkins. Добавьте к этому парсер на основе Publican, который превращает исходные файлы DocBook и AsciiDoc во всевозможные форматы с унифицированным стилем, автоматически публикует на пользовательском портале, объединяет запросы и проверки контента с GitLab, и вот у вас в руках довольно солидный набор инструментов. В плане автоматизации, само собой разумеется, документация API должна за многое благодарить такие инструменты как JavaDoc, Sphinx и AsciiDoctor. Недавно последним писком моды стало модульное тестирование не только для кода, но и для документации. Подающие надежду инструменты вроде Hemingway и Emender не исправят за вас грамматику, но зато проанализируют ваш контент и сообщат о частых лингвистических промахах, таких, как слишком сложные предложения, неоднозначные глаголы и пассивный залог. Надеюсь, в будущем мы увидим больше пользы от инструментов, поскольку они могут автоматизировать самые трудоемкие задачи редактора и помочь нам сохранить целостность и лаконичность. Постоянная поставкаВ отличие от разработки, в сфере документации реализация этого принципа больше фокусируется на асинхронной публикации контента, что в основном означает, что мы можем не связывать поставку контента с поставкой ПО. Свобода! Свобода публиковать контент, когда нам нужно, свобода быть гибкими настолько, насколько мы можем (временами даже более гибкими, чем наши коллеги-разработчики). Свобода, так скажем, латать дыры в готовом продукте и вносить улучшения в ранее выпущенный контент. Те, кто трудится над проектами открытого ПО, могут похихикать над моим восторгом, поскольку им-то внести правку в документацию - что страницу в Wiki переделать, но в промышленном мире это серьезная задача, и данный подход - это еще одна причина любить компании открытого ПО, где влияние коммьюнити очень чувствуется и приветствуется. У нас в Red Hat вся документация для официальных релизов продукта доступна общественности на пользовательском портале, что означает, что в случае необходимости модицифировать контент всё, что нам нужно - это пересобрать книгу и загрузить изменения. Курирование контента стало естественной частью нашей работы, и мы стараемся балансировать между выпущенным контентом и созданием нового, когда планируем свои задачи. Эта практика очень удобна и тогда, когда нужно срочно поправить документацию из-за Heartbleed или Poodle, что часто затрагивает сразу многие продукты, вследствие чего и книги. Как мы управляем этими асинхронными циклами публикации? Это зависит от продукта и от команды. Некоторые из наших команд разработчиков используются методики, родственные Agile, поэтому команды технических писателей могут подстраивать под них свои итерации. Некоторые писательские команды задействовали Agile независимо от разработчиков. А есть те, кто вообще не использует Agile, а вместо того они относят больше задач по курированию контента на начало цикла релиза, а относящееся к релизу писательство - на более поздние фазы, когда функционал уже готов к документированию. Сотрудничество«Никто не живет в вакууме!» - кажется, я часто повторяю эту фразу в последнее время, и на то есть причина: без сотрудничества не было бы ПО с открытым исходным кодом. В дополнение к сфокусированной на пользователе стратегии в плане контента, мы должны, создавая документацию, учитывать и наших заинтересованных лиц. Итак, с кем же мы должны сотрудничать? Для начала - со всеми, кто вовлечен в создание ПО. Разработчиками, тестировщиками, менеджерами продукта, дизайнерами, инженерами поддержки, переводчиками, кого только нет! Мы все варимся в этом вместе, и многое можно приобрести, выступая как единая команда продукта или, как минимум, повысив уровень коммуникации между командами. Не будем также забывать и собственно о пользователях - от членов сообщества открытого ПО до корпоративных клиентов и команд, которые работают с клиентами. Большая часть сообществ открытого ПО уже использует рабочие процессы совместной разработки с различными подходами к проверке кода и общему управлению, и всё больше данные практики применяются и к документации. Такие проекты, как Mozilla Developer Network, показывают, как принципы сотрудничества, присущие сообществу открытого ПО, внедряются и в сообществе контента, и на странице сообщества OpenStack можно прочитать: «С документацией надо обращаться, как с кодом, созданным сообществом». Дорога, которую предстоит пройти сотрудничеству в проектах открытого ПО, еще длинна (и все еще строится), но об этом будет подробнее в следующей статье! Стратеги контента в Red Hat теперь имеют официальное место и голосуют на всех встречах по планированию и запуску продукта, наряду с представителями всех ролей в релизе продукта. В дополнение к внутренним заказчикам, мы также реализовали программу обратной связи, чтобы собирать фидбэк о нашей документации как непосредственно от потребителей, так и от менеджеров техподдержки и других команд, которые работают с потребителем. Такой тип сотрудничества с потребителем для нас вещь довольно новая, но я уверена, что это поможет нам оптимизировать стратегию планирования контента, а в паре с принципом непрерывной поставки позволит быстро усовершенствовать и исправлять контент для наших потребителей, которые из простых пользователей превращаются в тех, кто вносит свой вклад. Что дальше?Теперь у нас есть практически все кусочки паззла; мы убедили менеджеров или высшее руководство, что ценный контент лучше полного, и создали все технические условия, чтобы беспрепятственно его поставлять. И все, что осталось, - заставить кого-то всё это написать, да? Ну, это зависит от многого. Когда в названии твоей должности значится слово «писатель», то так или иначе чего-то такого от тебя и ждут. Но как совладать с непостоянной армией тех, кто вносит свой вклад в открытое ПО, в основном добровольно жертвуя временем, чтобы написать код в твоем проекте, и не имеет ни времени, ни мотивации, ни уверенности в языковых навыках, чтобы написать все те документы, о которых вы все время говорите?
Оригинал: http://opensource.com/business/15/7/documentation-devops Об авторе: в настоящее время Майки работает старшим техническим писателем для платформы OpenStack в Red Hat, в Брно, Чехия. В свободное время, которого вечно не хватает, она возглавляет коммьюнити Write the Docs Europe, организует воркшопы для Django Girls, выступает в роли коуча в проектах с открытым кодом, страстно выступает на конференциях открытого ПО обо всем, что касается документации и Agile, много пишет в Твиттер и мало спит. Перевод: Александра Родсет |
Еще интересные статьи на эту тему:
|
