Предполагаю, что вам, уважаемые читатели, в своей работе доводилось иметь дело с технической документацией и, возможно, даже с теми, кто ее создает — с техническими писателями. А в нашем блоге вы могли познакомиться с техническим писателем из команды 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 (на англ. языке)
