[XML, Usability, Agile, Подготовка технической документации] Техническая документация и Agile: совместить несовместимое
Автор
Сообщение
news_bot ®
Стаж: 6 лет 9 месяцев
Сообщений: 27286
Привет, меня зовут Татьяна, я — старший технический писатель в Центре разработки Orion Innovation. Технический писатель — это такое промежуточное звено в IT, где-то между физиками и лириками. Мы часто работаем довольно обособленно от разработки, но это невозможно, если проект ведется в Agile или переходит на Agile. «Работающий продукт важнее исчерпывающей документации», — гласит один из постулатов Agile-манифеста. В реальных условиях это утверждение часто и максималистично превращается в «документация в agile не важна вообще», и, конечно, это неправильно, особенно когда мы говорим о документации для конечного пользователя. В этой статье речь пойдет не о важности документации как таковой, об этот вопрос сломано уже много копий. А о том, как встроить ее в Agile-процесс гармонично и с минимальным количеством острых углов. Недавно нам пришлось переводить в Agile крупный проект. Несколько Scrum-команд разработчиков, довольно обширный стэк документов, многие из которых устарели просто потому, что в каскадной разработке писатели не успевали их обновлять. Служба поддержки завалена жалобами от пользователей: «Но у вас же так написано, почему не работает?» Сразу спойлер: интеграция техписов в Agile прошла успешно, хоть и не всегда гладко. Благодаря этому опыту, мы выработали несколько рекомендаций, которыми хочу поделиться.Документация в AgileВ структуре IT-проекта технические писатели часто стоят немного особняком: им не обязательно нужно специализированное техническое образование и опыт написания кода. Более того, тем, кто работает с пользовательской документацией, девелоперская профдеформация может даже вредить — все ведь слышали шутки про перевод с программистского на человеческий? Это само по себе уже создает водораздел между разработчиками и техписателями. Но и процесс создания документации, на первый взгляд, не особо вписывается в Agile, хотя бы потому, что проще всего документировать продукт по мере его готовности, а не во время его разработки. 
Решение проблемы здесь выглядит довольно простым: документация должна создаваться синхронно с процессом разработки. На практике это тот случай, когда сказать значительно проще, чем сделать. Но плюшки от успешной интеграции стоят того, чтобы этим заняться. Конечно, потребуются усилия с двух сторон, и от технических писателей, и от разработчиков. Вот некоторые шаги, которые могут предпринять техписатели, чтобы успевать за Agile процессом.Техписам1.1. Переход на XML-редакторы и DITA-инструментыДля успешной работы в Agile-среде это первейшая необходимость. Если ваша документация — это развесистые файлы в Word, вы никогда не успеете за Аgile-процессом просто потому, что в Word нет инструментов для быстрого апдейта и реюза. Зато они есть в DITA-редакторах, которые обеспечат ту самую техническую базу, необходимую, чтобы чисто физически мочь выдавать обновленные документы к каждому релизу или, если понадобится, в конце каждого спринта. Более подробно об информационной архитектуре DITA можно почитать, например, вот здесь.
1.2. Активная коммуникацияМногие не видят смысла в постоянном присутствии техписателей на скрам-митингах, потому что текущие вопросы разработки нас действительно мало касаются. И тем не менее, если вы техписатель в Agile-проекте, обязательно подключитесь ко всем внутренним чатам и каналам, следите за командным слаком, багтрекерами, ходите на скрам-митинги, планирования и ревью спринтов. Пусть даже вы формально присутствуете на большинстве из них молчаливым привидением, рано или поздно ваше количественное присутствие обязательно перерастет в качественное.
Прежде всего, вы сможете гораздо лучше ориентироваться во внутренней кухне проекта, а быстрый сбор информации в Аgile для техписателя — один из главных челленджей. Кроме того, задача сделать документацию равноценной по важности частью проектных deliverables, скорее всего, ляжет на ваши плечи. Поэтому не бойтесь, что будете мозолить разработчикам и тестировщикам глаза. Именно ваше активное участие в процессе, которое начнется с активного присутствия, поможет решить эту задачу. По опыту, лучше отфильтровать море нерелевантной информации, чем потом бегать за разработчиками в поисках нужной.1.3. Пользуйтесь инструментами и практиками Agile в работеЭто может звучать как слишком очевидная рекомендация, если подразумевается только использование JIRA или аналогов для постановки и отслеживания задач. Но ключевое слово все-таки «практики».Например, правильная приоритизация по Agile вполне позволит техписателю решить самую большую проблему в работе: выдавать некий MVP в конце каждого спринта. В идеале, то что разрабатывается в текущем спринте, лучше всего документировать в нем же, чтобы взаимодействовать с разработчиками, пока их участие в проекте еще свежо и они не переключились на другие задачи. На практике это сложно осуществить, потому что один технический писатель может работать с несколькими командами девелоперов.Если ставить самую высокую приоритетность задачам по текущим обновлениям и багам, вы сможете документировать их в том же спринте или в следующем, получать комментарии от разработчиков оперативно, проводить демо документации на ревью спринтов. А вот задачи, которые меньше зависят от текущей разработки, например, реструктуризацию документов, работу с legacy-материалом, можно делать и вне привязки к конкретному спринту или релизу.Если над проектом работают несколько техписателей и проект достаточно крупный, имеет смысл сделать само звено техписов отдельной Scrum-командой со всеми вытекающими. Это здорово помогает структурировать всю работу и поддерживать нужный темп.1.4. Вовлекайте разработчиковЗдесь иногда придется проявлять чудеса дипломатии и недюжинный дзен. Не бойтесь задавать глупые вопросы. Старайтесь получить обратную связь от разработчиков на нескольких ключевых стадиях создания материала: во время планирования документации на спринт или на релиз, чтобы правильно оценить и понять новый функционал. SME-ревью — после написания первой версии документации, и формальное ревью — перед окончанием работы. Лучше на берегу договориться с разработчиками о том, как и когда они будут проводить ревью документации, чтобы они включили это время в планирование спринтов. А еще лучше — делать все ревью в баг-трекере, в котором работают ваши разрабы.Конечно, усилиями только технических писателей добиться хорошего уровня интеграции документации в Agile не получится. Вот что можно сделать разработчикам, чтобы помочь своим техписателям.ДевелоперамТехнический писатель — ваш первый пользователь. Именно взгляд техписателя на продукт наиболее приближен к пользовательскому. Он не знает много внутреннего контекста, его технический кругозор во многом похож на пользовательский и его задача — рассказать вашим юзерам в доступной форме, как эффективно пользоваться продуктом. Поэтому постарайтесь не сбрасывать с счетов вопросы техписов, которые кажутся нерелевантными или неважными. Если они возникли у техписателя, с большой вероятностью могут возникнуть и у пользователя. Именно поэтому технического писателя можно и нужно привлекать к командной работе над проектом во всем, что касается опыта пользователя и usability. 2.1. Включите технических писателей в Scrum-команду формальноА именно: включите их в список командных рассылок, добавляйте в приглашения на все командные митинги, обсуждения, демо и ревью. Да, не все они даже косвенно имеют отношение к документации, но важны для того, чтобы техписатели почувствовали себя полноправными членами команды. Впоследствии они сами определятся с тем, какие митинги полезны для их работы, но на самом деле, полезным могут оказаться все. Включите документацию в список deliverables и Definition of Done как полноценную часть проекта.
2.2. Заводите документационные тикетыТехнические писатели в основном работают с информацией по текущему релизу, но часто бывает так, что в процессе разработки меняются фичи, которые вышли в релиз какое-то время назад. Это могут быть незначительные изменения в интерфейсе, исправление багов, какие-то смежные с новыми фичами доработки, выявленные тестерами ограничения, которые должны быть отражены в пользовательской документации. Конечно, команда техписателей старается реагировать на эти изменения, но если у вас есть возможность, всегда сообщайте о них и отслеживайте выполнение этих задач. Лично мне очень помогло создание отдельной странички на Confluence, куда разработчики со всего проекта скидывали изменения в софте, которые, по их мнению, нужно было отразить в документах. 2.3. Участвуйте в планировании документацииЭто может здорово сократить вам и всей команде разработчиков время и нервы, которые так или иначе придется потратить на работу с документацией и техписателями. Запланированная в начале спринта встреча поможет вам сориентироваться по степени вашего участия, а техписателю — оценить информационные ресурсы и значительно сократит количество вопросов от техписов в процессе создания документации. Обязательно выделите в спринте время на SME-ревью всего нового контента или делегируйте это разработчикам из команды, чтобы не разрываться под конец спринта или релиза.
2.4. Предоставьте полную информациюСтранички на Confluence или Вики, тест-планы, HLD-документы, полезным может оказаться все. Чем больше исходных материалов, тем самостоятельнее ваши технические писатели. Заранее предоставленная информация позволит техписателям начать документировать фичи, которые вы только начали разрабатывать, отслеживать изменения в разработке на ваших же ресурсах и вносить нужные правки.2.5. Доверяйте вашему техписуВ процессе ревью документации вы запросто можете обнаружить, что где-то в корне не согласны с содержанием или формой. А может быть, и с тем, и с другим. Причин для этого может быть много, но не все они будут связаны с тем, что технический писатель не понял материал и неверно его изложил. Техническая документация часто следует определенному и довольно жесткому стилю и требованиям к тому, как должна быть изложена информация и какая информация должна быть донесена до пользователя, а какая — остаться за кадром. Если в написанном нет технических противоречий, но у вас есть вопросы к языку или формулировке, то, возможно, стоит оставить последнее слово за техническим писателем.Ну и пара слов о пресловутых плюшках. Рабочий продукт важнее, но если можно убить двух зайцев одним ударом, почему бы этого не сделать. Рабочая, актуальная документация значительно снижает нагрузку на службу техподдержки, что подтверждают многие исследования. Кроме того, технические писатели — в какой-то мере дополнительное звено тестирования продукта. К тому же, они обладают пользовательским взглядом. Поэтому внедрение документации в Agile позволит разработке пользоваться этими преимуществами.ЗаключениеНаш опыт показывает, что документация в Agile более чем реализуема, если следовать нескольким ключевым принципам:
- Четкое планирование контента и расстановка приоритетов. Прямо-таки обязательное заполнение Severity и Priority.
- Активная, регламентированная коммуникация между разработчиками и писателями.
- Обязательное использование Agile-инструментов и практик техписами.
===========
Источник:
habr.com
===========
Похожие новости:
- [Управление проектами, Agile, Читальный зал, 1С] Собеседование scrum-мастера в 1Сную контору
- [Хостинг, Service Desk, Законодательство в IT, IT-компании] Как написать регламент, чтобы клиентов не тошнило, а бизнес получал сарафанку
- [Тестирование IT-систем, Тестирование веб-сервисов, Тестирование мобильных приложений, Подготовка технической документации] Юзер-стори идеальная, а багов 100500? Как мы тестируем документацию
- [Тестирование IT-систем, Usability, Аналитика мобильных приложений, Законодательство в IT, IT-компании] Тинькофф, Я вас люблю и ненавижу…
- [Usability, Развитие стартапа, Бизнес-модели] Всё получится, если МАМАвТЕМЕ: от идеи до MVP образовательного маркетплейса
- [Высокая производительность, Программирование, C++] Производительность компилятора при работе с концептами в C++20
- [Agile] Мы решили внедрить Agile-Lean принципы в процесс разработки “на ходу” и вот что из этого получилось
- [ERP-системы, Agile] Как мы замиксовали Agile для внедрения новой ERP-платформы
- [Подготовка технической документации] Как писать хорошую документацию
- [Анализ и проектирование систем, Agile] Краеугольный камень анализа. Часть 1
Теги для поиска: #_xml, #_usability, #_agile, #_podgotovka_tehnicheskoj_dokumentatsii (Подготовка технической документации), #_agile, #_technical_writing, #_technical_writer, #_dita, #_documentation, #_dokumentatsija (документация), #_tehnicheskij_pisatel (технический писатель), #_tehnicheskaja_dokumentatsija (техническая документация), #_blog_kompanii_orion_innovation (
Блог компании Orion Innovation
), #_xml, #_usability, #_agile, #_podgotovka_tehnicheskoj_dokumentatsii (
Подготовка технической документации
)
Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Текущее время: 24-Ноя 07:41
Часовой пояс: UTC + 5
| Автор | Сообщение |
|---|---|
|
news_bot ®
Стаж: 6 лет 9 месяцев |
|
 Привет, меня зовут Татьяна, я — старший технический писатель в Центре разработки Orion Innovation. Технический писатель — это такое промежуточное звено в IT, где-то между физиками и лириками. Мы часто работаем довольно обособленно от разработки, но это невозможно, если проект ведется в Agile или переходит на Agile. «Работающий продукт важнее исчерпывающей документации», — гласит один из постулатов Agile-манифеста. В реальных условиях это утверждение часто и максималистично превращается в «документация в agile не важна вообще», и, конечно, это неправильно, особенно когда мы говорим о документации для конечного пользователя. В этой статье речь пойдет не о важности документации как таковой, об этот вопрос сломано уже много копий. А о том, как встроить ее в Agile-процесс гармонично и с минимальным количеством острых углов. Недавно нам пришлось переводить в Agile крупный проект. Несколько Scrum-команд разработчиков, довольно обширный стэк документов, многие из которых устарели просто потому, что в каскадной разработке писатели не успевали их обновлять. Служба поддержки завалена жалобами от пользователей: «Но у вас же так написано, почему не работает?» Сразу спойлер: интеграция техписов в Agile прошла успешно, хоть и не всегда гладко. Благодаря этому опыту, мы выработали несколько рекомендаций, которыми хочу поделиться.Документация в AgileВ структуре IT-проекта технические писатели часто стоят немного особняком: им не обязательно нужно специализированное техническое образование и опыт написания кода. Более того, тем, кто работает с пользовательской документацией, девелоперская профдеформация может даже вредить — все ведь слышали шутки про перевод с программистского на человеческий? Это само по себе уже создает водораздел между разработчиками и техписателями. Но и процесс создания документации, на первый взгляд, не особо вписывается в Agile, хотя бы потому, что проще всего документировать продукт по мере его готовности, а не во время его разработки.  Решение проблемы здесь выглядит довольно простым: документация должна создаваться синхронно с процессом разработки. На практике это тот случай, когда сказать значительно проще, чем сделать. Но плюшки от успешной интеграции стоят того, чтобы этим заняться. Конечно, потребуются усилия с двух сторон, и от технических писателей, и от разработчиков. Вот некоторые шаги, которые могут предпринять техписатели, чтобы успевать за Agile процессом.Техписам1.1. Переход на XML-редакторы и DITA-инструментыДля успешной работы в Agile-среде это первейшая необходимость. Если ваша документация — это развесистые файлы в Word, вы никогда не успеете за Аgile-процессом просто потому, что в Word нет инструментов для быстрого апдейта и реюза. Зато они есть в DITA-редакторах, которые обеспечат ту самую техническую базу, необходимую, чтобы чисто физически мочь выдавать обновленные документы к каждому релизу или, если понадобится, в конце каждого спринта. Более подробно об информационной архитектуре DITA можно почитать, например, вот здесь.  1.2. Активная коммуникацияМногие не видят смысла в постоянном присутствии техписателей на скрам-митингах, потому что текущие вопросы разработки нас действительно мало касаются. И тем не менее, если вы техписатель в Agile-проекте, обязательно подключитесь ко всем внутренним чатам и каналам, следите за командным слаком, багтрекерами, ходите на скрам-митинги, планирования и ревью спринтов. Пусть даже вы формально присутствуете на большинстве из них молчаливым привидением, рано или поздно ваше количественное присутствие обязательно перерастет в качественное.  Прежде всего, вы сможете гораздо лучше ориентироваться во внутренней кухне проекта, а быстрый сбор информации в Аgile для техписателя — один из главных челленджей. Кроме того, задача сделать документацию равноценной по важности частью проектных deliverables, скорее всего, ляжет на ваши плечи. Поэтому не бойтесь, что будете мозолить разработчикам и тестировщикам глаза. Именно ваше активное участие в процессе, которое начнется с активного присутствия, поможет решить эту задачу. По опыту, лучше отфильтровать море нерелевантной информации, чем потом бегать за разработчиками в поисках нужной.1.3. Пользуйтесь инструментами и практиками Agile в работеЭто может звучать как слишком очевидная рекомендация, если подразумевается только использование JIRA или аналогов для постановки и отслеживания задач. Но ключевое слово все-таки «практики».Например, правильная приоритизация по Agile вполне позволит техписателю решить самую большую проблему в работе: выдавать некий MVP в конце каждого спринта. В идеале, то что разрабатывается в текущем спринте, лучше всего документировать в нем же, чтобы взаимодействовать с разработчиками, пока их участие в проекте еще свежо и они не переключились на другие задачи. На практике это сложно осуществить, потому что один технический писатель может работать с несколькими командами девелоперов.Если ставить самую высокую приоритетность задачам по текущим обновлениям и багам, вы сможете документировать их в том же спринте или в следующем, получать комментарии от разработчиков оперативно, проводить демо документации на ревью спринтов. А вот задачи, которые меньше зависят от текущей разработки, например, реструктуризацию документов, работу с legacy-материалом, можно делать и вне привязки к конкретному спринту или релизу.Если над проектом работают несколько техписателей и проект достаточно крупный, имеет смысл сделать само звено техписов отдельной Scrum-командой со всеми вытекающими. Это здорово помогает структурировать всю работу и поддерживать нужный темп.1.4. Вовлекайте разработчиковЗдесь иногда придется проявлять чудеса дипломатии и недюжинный дзен. Не бойтесь задавать глупые вопросы. Старайтесь получить обратную связь от разработчиков на нескольких ключевых стадиях создания материала: во время планирования документации на спринт или на релиз, чтобы правильно оценить и понять новый функционал. SME-ревью — после написания первой версии документации, и формальное ревью — перед окончанием работы. Лучше на берегу договориться с разработчиками о том, как и когда они будут проводить ревью документации, чтобы они включили это время в планирование спринтов. А еще лучше — делать все ревью в баг-трекере, в котором работают ваши разрабы.Конечно, усилиями только технических писателей добиться хорошего уровня интеграции документации в Agile не получится. Вот что можно сделать разработчикам, чтобы помочь своим техписателям.ДевелоперамТехнический писатель — ваш первый пользователь. Именно взгляд техписателя на продукт наиболее приближен к пользовательскому. Он не знает много внутреннего контекста, его технический кругозор во многом похож на пользовательский и его задача — рассказать вашим юзерам в доступной форме, как эффективно пользоваться продуктом. Поэтому постарайтесь не сбрасывать с счетов вопросы техписов, которые кажутся нерелевантными или неважными. Если они возникли у техписателя, с большой вероятностью могут возникнуть и у пользователя. Именно поэтому технического писателя можно и нужно привлекать к командной работе над проектом во всем, что касается опыта пользователя и usability. 2.1. Включите технических писателей в Scrum-команду формальноА именно: включите их в список командных рассылок, добавляйте в приглашения на все командные митинги, обсуждения, демо и ревью. Да, не все они даже косвенно имеют отношение к документации, но важны для того, чтобы техписатели почувствовали себя полноправными членами команды. Впоследствии они сами определятся с тем, какие митинги полезны для их работы, но на самом деле, полезным могут оказаться все. Включите документацию в список deliverables и Definition of Done как полноценную часть проекта.  2.2. Заводите документационные тикетыТехнические писатели в основном работают с информацией по текущему релизу, но часто бывает так, что в процессе разработки меняются фичи, которые вышли в релиз какое-то время назад. Это могут быть незначительные изменения в интерфейсе, исправление багов, какие-то смежные с новыми фичами доработки, выявленные тестерами ограничения, которые должны быть отражены в пользовательской документации. Конечно, команда техписателей старается реагировать на эти изменения, но если у вас есть возможность, всегда сообщайте о них и отслеживайте выполнение этих задач. Лично мне очень помогло создание отдельной странички на Confluence, куда разработчики со всего проекта скидывали изменения в софте, которые, по их мнению, нужно было отразить в документах. 2.3. Участвуйте в планировании документацииЭто может здорово сократить вам и всей команде разработчиков время и нервы, которые так или иначе придется потратить на работу с документацией и техписателями. Запланированная в начале спринта встреча поможет вам сориентироваться по степени вашего участия, а техписателю — оценить информационные ресурсы и значительно сократит количество вопросов от техписов в процессе создания документации. Обязательно выделите в спринте время на SME-ревью всего нового контента или делегируйте это разработчикам из команды, чтобы не разрываться под конец спринта или релиза.  2.4. Предоставьте полную информациюСтранички на Confluence или Вики, тест-планы, HLD-документы, полезным может оказаться все. Чем больше исходных материалов, тем самостоятельнее ваши технические писатели. Заранее предоставленная информация позволит техписателям начать документировать фичи, которые вы только начали разрабатывать, отслеживать изменения в разработке на ваших же ресурсах и вносить нужные правки.2.5. Доверяйте вашему техписуВ процессе ревью документации вы запросто можете обнаружить, что где-то в корне не согласны с содержанием или формой. А может быть, и с тем, и с другим. Причин для этого может быть много, но не все они будут связаны с тем, что технический писатель не понял материал и неверно его изложил. Техническая документация часто следует определенному и довольно жесткому стилю и требованиям к тому, как должна быть изложена информация и какая информация должна быть донесена до пользователя, а какая — остаться за кадром. Если в написанном нет технических противоречий, но у вас есть вопросы к языку или формулировке, то, возможно, стоит оставить последнее слово за техническим писателем.Ну и пара слов о пресловутых плюшках. Рабочий продукт важнее, но если можно убить двух зайцев одним ударом, почему бы этого не сделать. Рабочая, актуальная документация значительно снижает нагрузку на службу техподдержки, что подтверждают многие исследования. Кроме того, технические писатели — в какой-то мере дополнительное звено тестирования продукта. К тому же, они обладают пользовательским взглядом. Поэтому внедрение документации в Agile позволит разработке пользоваться этими преимуществами.ЗаключениеНаш опыт показывает, что документация в Agile более чем реализуема, если следовать нескольким ключевым принципам:
=========== Источник: habr.com =========== Похожие новости:
Блог компании Orion Innovation ), #_xml, #_usability, #_agile, #_podgotovka_tehnicheskoj_dokumentatsii ( Подготовка технической документации ) |
|
Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Текущее время: 24-Ноя 07:41
Часовой пояс: UTC + 5