Ниже мы представляем интервью Анны Джентл (Anne Gentle), координатора по разработке документации сообщества OpenStack.
Mirantis: Расскажите о себе.
Анна Джентл: Я работаю в штате компании Rackspace и занимаюсь написанием документации OpenStack. Я – второй сотрудник, которого наняла компания Rackspace специально для работы с OpenStack. Это для меня стало счастливым случаем. В 2009 году я написала книгу о том, как совместно работать над документацией в сообществе, и я неоднократно участвовала в создании документации для проектов с открытым кодом. И вот появилась эта работа, у меня прямо рядом с домом, в Остине (Техас) и я схватилась за неё.
Вопрос: В чем ключевое различие между документацией для проекта с открытым кодом и закрытым кодом?
Ответ: Первое большое отличие – это заинтересованность в открытости во всем, от инструментов разработки документации до публикации. В первую же неделю работы меня даже спросили, все ли наши шрифты используются по принципу открытого источника! Наши инструменты открыты для всех – вы можете свободно писать документацию или компоновать части или повторно использовать тексты. Второе отличие – сама документация. В условиях закрытого кода документация ограничена юридическими требованиями в плане соблюдения соглашений об уровне обслуживания или биллинга. Идея в основе открытых, совместно разрабатываемых документов в том, что любой может их редактировать. Также в некоторых сообществах существует определенная этика при определении авторства контента. Это хороший сценарий для лицензий Creative Commons (с указанием авторства).
Существует большой диапазон проектов, но большинство вариантов связано с лицензированием и свободой обращения с контентом. Также я верю в то, что в проектах с открытым кодом происходит множество интересных инноваций. По тем же причинам, по которым вы занимаетесь разработкой с открытым кодом, люди хотят участвовать в совместной разработке документов.
Вопрос: Что особенного в открыто разрабатываемых документах?
Ответ: При разработке документации важна дисциплина, а открытая разработка, как ни странно, самоорганизуется. Проекты, где документы максимально привязаны к коду, обычно очень дисциплинированы. Ты находишь ошибку в документации, а люди могут взять её на исправление.
Со временем wiki-системы стали более организованы и превратились в системы управления контентом, а настоящие свободные wiki-системы, основанные на оригинальной идее Ворда Каннингема (Ward Cunningham), все еще очень ценный механизм и ценная идея работы с контентом. Больше, чем wiki-системы, мне нравятся инновационные сессии разработки документации, как, например, спринт-методы (Book Sprint). Мне также нравится отношение к документам как к коду, поиск способов автоматической генерации документов, которые помогают пользователям и соответствуют коду.
Вопрос: Какие принципы применимы при открытой разработке документации?
Ответ: Открытая разработка документации – это процесс, в котором присутствует как дисциплина, так и дипломатия. Вам необходимо найти способы внедрить процедуру разработки документации, но при этом быть очень дипломатичным, потому что люди добавляют контент и ценят его и хотят, чтобы он существовал в официальном виде.
Один из наиболее интересных методов — Book Sprint. Вы собираете группу писателей, организуете обмен знаниями и пытаетесь из всего массива выделить организованную структуру. При этом используете инструмент Booktype, и очень классно, что Sourcefabric может поддерживать для вас инстанс.
При разработке Руководства по процессам, все, кто присутствовал на спринте, знали, как использовать наши инструменты на основе XML, и затем смогли немедленно использовать Booktype, а потом, после спринта, когда содержимое устоялось и приобрело вес, мы его внедрили в ряд инструментов на основе XML.
В инструментах на основе XML классно то, что их же используют O’Reilly. Ценность XML в том, что он позволяет нам повторно использовать куски содержимого, помечать их тегами или избегать повторных переводов. Из кусков контента вы затем можете получить множество документов на выходе. Мы можем получить ePub, если хотим. А затем, по мере работы с контентом вы понимаете, что такой тип разбиения на части на основе XML – это наилучший способ объять необъятное и организовать его.
Документы встраиваются в методы разработки кода. Мы используем Git. Мы используем Gerrit. Мы проверяем тексты друг друга, по аналогии с правкой фрагмента кода. Фрагмент кода необходимо создать локально, затем убедиться, что он попал в сборку и прошел проверку. Jenkins проверяет все наши тексты и автоматически выполняет публикацию.
Один из основополагающих принципов в том, что вы не хотите раздражать или вводить в уныние своим подходом к документации. Люди ищут группы, которые сходны с ними. Вы можете сказать: “Не, это не мои люди” или “Это не моя область интересов.” Один из принципов открытой разработки документации для меня — это личное взаимодействие. Люди должны понимать, что это – свои, что они имеют общие цели.
Я пытаюсь соотнести работу и компетенцию, чтобы вы не разочаровались и не ушли. Какие задачи интересны для вас с технической точки зрения? Я думаю, один из основополагающих принципов открытой разработки – это соответствие людей и задач.
Вопрос: Видите ли вы различия во вкладе в документацию OpenStack в зависимости от опыта людей?
Ответ: Для релиза Grizzly 50 процентов всех правок, за исключением книг с описанием API-интерфейса, были выполнены тремя людьми, в том числе мной (смеясь). Но мы пытаемся привлечь больше людей к большему объему работы.
Но самое интересное, что у нас было 79 участников проекта в общем. Эти люди делали шесть или восемь патчей, но у них были и специальные знания. Они знали, как настроить Cinder, что необходимо было сделать, какую часть содержимого надо написать, чтобы реализовать задуманное.
Вам нужна основная группа, которая знает все обо всех фрагментах в базе данных или в основной ее части, но вам нужны и узкие специалисты. С ростом проекта важно определить приоритеты – остаться ли на высоком уровне или работать от проекта к проекту.
Существуют инструкции для администраторов для каждого проекта, но они все равно должны содержать указания по установке и настройке ПО. Руководство по хранению содержит кучу информации, известной только сотрудникам, занимающимся драйверами. Действительно трудно определить, необходимо ли поддерживать руководства администратора для каждого проекта. Сейчас в работе 10 проектов и ещё 2 проекта рассматриваются. Мы не можем поддерживать 10 руководств админа, особенно при условии, что некоторые из них взаимосвязаны. Мы исследуем и ищем наилучший способ а) привлечения участников, но также и б) помощи им в поиске проекта для работы.
Есть и другой аспект – мы хотим, чтобы разработчики писали для разработчиков и т.д. Методология Book Sprint выявила для меня, что Руководство по процессам сработало, потому что его авторы выполняют эти процессы каждый день. То же самое я вижу в руководстве по укреплению безопасности; эти ребята дышат и живут этой темой.
Вопрос: Что удерживает людей от вклада в документацию и от участия в ней?
Ответ: Я думаю, что многие люди видят, что мы используем GitHub, Gerrit и XML и думают: “Ох, это не наша специальность!”…и отходят. Я вводила в курс дела десятки людей, которые подписывали лицензионное соглашение участника (CLA). Вы должны быть достаточно терпеливыми, чтобы пройти это, так как вы просто пишете документацию или хотите исправить опечатку, но вы должны пройти весь процесс подписания соглашения CLA. И у меня есть твердое убеждение в том, что это нужно. Мне больше нравятся авторы документации, которые участвуют в OpenStack Foundation и в сообществе открытого кода, а не случайные люди.
И, наконец, простой объем знаний и требования к аппаратному обеспечению и техническому оснащению могут отпугивать людей.
Вопрос: Какой путь следует пройти от новичка до профессионала в плане документации в OpenStack?
Ответ: Есть пара возможных путей. Обязательно попробовать поработать с OpenStack, а затем увидеть, какая аудитория ваша. Затем начать с изучения документации: “Отвечает ли она на мои вопросы? Есть ли отсутствующие фрагменты?” И убедитесь в том, что вы примеряете на себя роль пользователя или разработчика, когда читаете документ.
Я думаю, что пользовательские группы начинают делать действительно классные вещи. Шон Робертс и Колин МакНамара – лидеры пользовательской группы San Francisco Bay User Group, и они ведут небольшой семинар о том, как писать документацию, потому что есть люди, хотящие овладеть OpenStack, а один из наилучших способов обучиться – это освоение инструментов и документов. И замечательный способ обучения – это запись того, что вы делаете.
У нас также много групп студентов, которые думают что-то вроде, “Я думаю, что документация – хорошая стартовая площадка”. Для них у нас есть список задач. Посмотреть, есть ли вводная информация в книге. Выполнить проверку орфографии. Проверить текст на правила использования прописных букв и т.п.
Я также думаю, что люди могут оценивать документы. Некоторые люди присылали мне PDF с правками. И это абсолютно нормально. Все, что угодно, чтобы начать читать, оценивать, выбирать, что они могут извлечь из этого огромного массива документации, “О, вот с чего я могу начать”.
Вопрос: Расскажите о лагере подготовки авторов документации?
Ответ: Наш лагерь подготовки – это способ построения связей между участниками и поощрения большего числа людей на ключевое участие в документации. Мы проводим его в Маунтейн Вью, в Калифорнии, 9 и 10 сентября.
Мы проходим по всем инструментам и процессам, чтобы все в достаточной мере освоили инструменты. Для процессов мы ответим на вопросы, как например “Нужно ли мне писать черновик для этого? Или это просто ошибка? Как мне определить, что делать? Как мне выбрать инструмент для проверки? Что такое Maven? Когда я добавляю новую книгу, что мне сделать, чтобы опубликовать ее? Как мне провести диагностику, если я внес изменение, но я не вижу его на сайте?” Это все в первый день.
А во второй день это скорее общение, где мы говорим о том, над чем можно работать. Вы не обязаны приняться за работу прямо в этот день, но многие говорят “Вот что собственно мы можем сделать со знанием, которое мы сейчас получили”. Во второй день мы искореняем ошибки в документации. Основная идея в том, чтобы новые участники сразу встраивались в ядро разработчиков документации.
Вопрос: Что насчет переводов?
Ответ: Настоящей ценностью для меня является, например, что однажды руководство по OpenStack будет написано на французском, и вместо перевода с английского на французский, будет обратный перевод. Мне не кажется, что английский всегда следует использовать как язык-источник. Это мое личное мнение, но мне не кажется, что первым вашим руководством по OpenStack обязательно должно быть руководство на английском.
Перевод документации сводится к расстановке приоритетов. Первым приоритетом для нас является перевод руководства по процессам, так как на него наибольший спрос. Дейзи, координатор переводов, на прошлой неделе спросила меня, что переводить следующим. И я ответила: “Честно говоря, я бы хотела увидеть переведенным это руководство пользователя, возможно после Руководства администратора. Попытаемся выйти на аудиторию операторов и администраторов на их языке”.
Вопрос: Благодарим вас за уделенное время.
Ответ: Спасибо.
ссылка на оригинал статьи http://habrahabr.ru/company/mirantis_openstack/blog/190624/
Добавить комментарий