Предполагаю, что вам, уважаемые читатели, в своей работе доводилось иметь дело с технической документацией и, возможно, даже с теми, кто ее создает — с техническими писателями. А в нашем блоге вы могли познакомиться с техническим писателем из команды Veeam.
Сегодня переходим на следующий уровень понимания того, как устроена разработка технической документации в Veeam Software.
КДПВ обманчива — никакое это не чудо, а такая же работа, как и у всех остальных коллег из R&D. Однако у тех, кто создает гайды, естьволшебные слова свои гайды по созданию гайдов! Вот такая вот рекурсия.
Подробнее — в рассказе моей коллеги Дарьи Шалыгиной.
Привет, меня зовут Даша, и я Content Quality Lead в компании Veeam Software. Я отвечаю за качество контента, создаваемого отделом технических писателей нашей компании. Практически, я технический писатель и редактор в одном флаконе. В мои обязанности входит:
Еще 3 года назад у нас было всего 8 технических писателей. Когда приходил кто-то новый, он изучал уже существующие гайды и начинал писать примерно в том же ключе. Это было чудесное время, когда у нас всех было примерно одинаковое чувство прекрасного, и мы могли без усилий прийти к единому пониманию, как писать документацию к нашим продуктам.
Время шло, компания росла, продуктов становилось все больше, и возникла необходимость в увеличении штата технических писателей. Сегодня нас уже 18 человек, и мы не планируем на этом останавливаться. Все бы хорошо, но внезапно оказалось, что при таком количестве человек договориться о прекрасном становится трудновато. Требуется время, время и еще раз время.
Чтобы сократить энергозатраты на передачу знаний вновь прибывающим, а также чтобы раз и навсегда зафиксировать, что есть «прекрасное» в технической документации Veeam, было принято решение создать наш собственный стайл гайд. Нужно сказать, что какие-то наметки на тему стиля уже существовали многие годы у нас в виде статей на Confluence и заметок на полях в блокнотах, но все это было неупорядоченно, разрозненно, и, конечно, ни о какой простоте использования и актуальности информации говорить не приходилось.
Было:
Когда мы создавали наш стайл гайд, мы взяли за основу 3 крупных гайда, которые обычно принято брать за образец при написании документации: (Chicago Manual of Style, Microsoft Manual of Style и DITA Best Practices), изучили ряд сторонних стайл гайдов, существующих у других компаний (например, IBM Style Guide, Documentation Style Guide for OpenSolaris и другие), провели исследование последних тенденций в области документации — и смешали все это с нашим собственным одиннадцатилетним опытом работы в Veeam Software.
Стало:
В итоге в Veeam Technical Writing Style Guide вошли такие злободневные темы, как структурирование контента по типам топиков, принципы Plain English, пунктуация, артикли, форматирование, оформление скриншотов и диаграмм, оформление ссылок на собственную и стороннюю документацию, а также полезные напоминалки на каждый день.
С появлением стайл гайда мы не только облегчили процесс передачи знаний новым сотрудникам, но и получили следующие преимущества:
Известный мем о том, как разительно меняется стиль письма после того, как вы поработали техническим писателем
Наш стайл гайд был создан не-носителями английского языка (non-native speakers) и предназначался для не-носителей же. Тем не менее, он был вычитан и выверен нашими коллегами-носителями (native speakers), лингвистами из отдела Marketing, которые имеют соответствующее образование, уже давно пишут тексты для сайта компании, и у которых разработан собственный стайл гайд, также основанный на принципах упомянутых гигантов отрасли.
Сейчас мы работаем над расширением нашей базы знаний. Мы хотим создать отдельные стайл гайды для справочных документов, таких как REST API Reference и PowerShell Reference. Для таких документов контент нужно структурировать особым образом, и это необходимо зафиксировать в целях поддержания единообразия между продуктами.
Мы будем рады, если наш стайл гайд будет полезен другим компаниям, которые пока еще только находятся в поисках собственного стиля. Советую еще посмотреть на раздел со справочной информацией, которая, по нашему опыту, частенько бывает нужна в работе — там много интересного. :)
Руководство Veeam Technical Writing Style Guide (на англ. языке)
Сегодня переходим на следующий уровень понимания того, как устроена разработка технической документации в Veeam Software.
КДПВ обманчива — никакое это не чудо, а такая же работа, как и у всех остальных коллег из R&D. Однако у тех, кто создает гайды, есть
Подробнее — в рассказе моей коллеги Дарьи Шалыгиной.
Привет, меня зовут Даша, и я Content Quality Lead в компании Veeam Software. Я отвечаю за качество контента, создаваемого отделом технических писателей нашей компании. Практически, я технический писатель и редактор в одном флаконе. В мои обязанности входит:
- ведение собственных проектов — как и у всех технических писателей, у меня есть моя зона ответственности, то есть ряд продуктов, для которых я создаю и поддерживаю документацию;
- обучение сотрудников уровня junior — я создала вводный курс для “новичков”, который я провожу, чтобы объяснять базовые правила написания документации;
- консультирование сотрудников уровней выше (experienced и senior) — у меня запланированы ежедневные сессии, в ходе которых любой член нашей команды может задать мне любой вопрос касательно документации (будь то формулировки, структура и прочее);
- проведение контрольного ревью — периодически я выборочно просматриваю документы членов нашей команды на предмет форматирования, ошибок, опечаток, несоответствия стилю и так далее.
Еще 3 года назад у нас было всего 8 технических писателей. Когда приходил кто-то новый, он изучал уже существующие гайды и начинал писать примерно в том же ключе. Это было чудесное время, когда у нас всех было примерно одинаковое чувство прекрасного, и мы могли без усилий прийти к единому пониманию, как писать документацию к нашим продуктам.
Время шло, компания росла, продуктов становилось все больше, и возникла необходимость в увеличении штата технических писателей. Сегодня нас уже 18 человек, и мы не планируем на этом останавливаться. Все бы хорошо, но внезапно оказалось, что при таком количестве человек договориться о прекрасном становится трудновато. Требуется время, время и еще раз время.
Чтобы сократить энергозатраты на передачу знаний вновь прибывающим, а также чтобы раз и навсегда зафиксировать, что есть «прекрасное» в технической документации Veeam, было принято решение создать наш собственный стайл гайд. Нужно сказать, что какие-то наметки на тему стиля уже существовали многие годы у нас в виде статей на Confluence и заметок на полях в блокнотах, но все это было неупорядоченно, разрозненно, и, конечно, ни о какой простоте использования и актуальности информации говорить не приходилось.
Было:
Когда мы создавали наш стайл гайд, мы взяли за основу 3 крупных гайда, которые обычно принято брать за образец при написании документации: (Chicago Manual of Style, Microsoft Manual of Style и DITA Best Practices), изучили ряд сторонних стайл гайдов, существующих у других компаний (например, IBM Style Guide, Documentation Style Guide for OpenSolaris и другие), провели исследование последних тенденций в области документации — и смешали все это с нашим собственным одиннадцатилетним опытом работы в Veeam Software.
Стало:
В итоге в Veeam Technical Writing Style Guide вошли такие злободневные темы, как структурирование контента по типам топиков, принципы Plain English, пунктуация, артикли, форматирование, оформление скриншотов и диаграмм, оформление ссылок на собственную и стороннюю документацию, а также полезные напоминалки на каждый день.
С появлением стайл гайда мы не только облегчили процесс передачи знаний новым сотрудникам, но и получили следующие преимущества:
- предотвращение необходимости поиска в сторонних стайл гадах и интернете ответов на вопросы, возникающие у нас на регулярной основе;
- мгновенное решение спорных моментов касательно языка, оформления и структуры документов;
- удобная навигация по собственной базе знаний;
- возможность предоставлять ссылки на определенные разделы коллегам из других отделов, прямо или косвенно работающим с написанием текстов (будь то Support или QA).
Известный мем о том, как разительно меняется стиль письма после того, как вы поработали техническим писателем
Наш стайл гайд был создан не-носителями английского языка (non-native speakers) и предназначался для не-носителей же. Тем не менее, он был вычитан и выверен нашими коллегами-носителями (native speakers), лингвистами из отдела Marketing, которые имеют соответствующее образование, уже давно пишут тексты для сайта компании, и у которых разработан собственный стайл гайд, также основанный на принципах упомянутых гигантов отрасли.
Сейчас мы работаем над расширением нашей базы знаний. Мы хотим создать отдельные стайл гайды для справочных документов, таких как REST API Reference и PowerShell Reference. Для таких документов контент нужно структурировать особым образом, и это необходимо зафиксировать в целях поддержания единообразия между продуктами.
Мы будем рады, если наш стайл гайд будет полезен другим компаниям, которые пока еще только находятся в поисках собственного стиля. Советую еще посмотреть на раздел со справочной информацией, которая, по нашему опыту, частенько бывает нужна в работе — там много интересного. :)
Руководство Veeam Technical Writing Style Guide (на англ. языке)
