Documentat.io

Мой доклад о том, как можно подходить к работе над техническими коммуникациями: что учитывать при работе с текстами, иллюстрациями и другими составляющими, от чего отталкиваться, к чему стремиться, с чем экспериментировать и что использовать как аппарат анализа.

Я поделюсь своими мыслями и наблюдениями касательно отбора и собеседования технических писателей: на что нужно обращать внимание в резюме и тестовых заданиях, какие профессиональные навыки являются необходимыми при приеме на работу, а какие — нет, и какую цель должно преследовать тестовое задание.

«Суровые сибирские техписатели читают и пишут код на С++!», и другие реальные истории из жизни штатного сотрудника томской компании UNIGINE, разрабатывающей собственную платформу 3D-графики.

В своем докладе я расскажу про:

• роль отдела технической документации для продукта;
• процессы и инструменты разработки документации в нашей компании;
• оценку качества разработанной документации;
• плюсы и минусы профессии;
• пути развития и карьерный рост специалистов;
• личные качества и знания, необходимые для достижения успеха в нашей отрасли.

В этом докладе я расскажу об основных возможностях сред разработки документации по принципу единого источника и рассмотрю самые популярные примеры применения этих возможностей на практике.

В 2014 году в России был официально принят профессиональный стандарт «Технический писатель». Мы поговорим о следующем:

• что это за стандарт и чем он полезен;
• как этот стандарт повлияет на рынок труда для документационных специалистов;
• что полезного из него могут почерпнуть технические писатели.

Мы поговорим о горизонтальном и вертикальном росте документационных специалистов, о приобретаемых и врожденных профессиональных навыках, и о том, как всё это коррелирует с интересностью задач и уровнем зарплат.

У программистов есть coding guidelines, у журналистов — редакционные политики, а что же есть у технических писателей? Правильно, внутренние гиды по стилю. Мы поговорим о том, какие задачи решает внутренний гид по стилю, почему он полезен не только документационной команде, с чего начать его создание и из каких кирпичиков его собирать.

Давайте ненадолго отвлечемся от изучения технической документации с точки зрения ее создателей и посмотрим на нее глазами руководителей и владельцев IT-компаний. В этом докладе мы поговорим о следующем:

• приносят ли технические писатели деньги своим компаниям;
• в какой момент документация становится конкурентным преимуществом компании;
• могут ли хорошо настроенные процессы документирования быть гарантией безопасности бизнеса;
• почему при общении с бизнесом нужно использовать термин «управление знаниями», а не «техническая документация/техническая коммуникация».

«Документация нужна нам через неделю. Описывать там особенно нечего, система из пары окошек. Информации море, есть техническое задание и внутренняя переписка разработчиков. В общем, все просто, недели даже много.»

Как часто задания на документирование звучат примерно так? И как часто именно такие формулировки вспоминаются в пять утра в день сдачи проекта, когда ничего еще не готово? Конечно, сердце чувствовало, что что-то не так, но как было отказать руководителю проекта, который расписывал перспективы столь радужно?

Для того, чтобы аргументированно ответить на вопросы вроде «Почему до завтра не получится?», «Да что здесь вообще описывать, откуда месяц?», «Зачем нам еще два технических писателя?» или просто «Когда будет готово?», нужно уметь оценить трудозатраты и сроки и убедительно обосновать их перед внешним или внутренним заказчиком. О том, как это сделать, и пойдет речь в докладе.

Мой доклад — об улучшении качества продукта путем улучшения качества документации, о влиянии технического писателя на производительность труда и о системном подходе к процессам документирования. Я расскажу о следующем:

• как хорошая документация уменьшает энтропию и увеличивает производительность труда;
• как выделить основные процессы документирования, типы основных документов и сделать четкое разделение операционных задач и задач развития;
• как правильно расставить приоритеты в условиях ограниченных ресурсов;
• о простых, но эффективных инструментах создания и хранения документации: JIRA, Confluence, SVN;
• о постановке задач на разработку документации и о контроле их выполнения.

Поделюсь опытом создания отдела документирования в крупной производственной компании. Расскажу про то, как и зачем нужно начинать документировать в любой непонятной ситуации. Покажу шишки от граблей и поясню, как их можно не получать и чем их лечить.

История о том, как мы в Plesk внедряем лучшие практики разработки ПО в разработку документации.

• какие проблемы были в разработке документации и как мы их решаем;
• что такое разработка документации как кода («docs like code»): легковесные языки разметки, контроль версий, непрерывная интеграция и поставка (CI/CD), контролируемая публикация, связь с разработкой и выпуском продукта;
• в чём польза для технических писателей и для бизнеса;
• как перейти на docs like code, не ломая процессы и не выкидывая легаси.

Доклад адресован всем, кто заинтересован в управлении знаниями в компании: техписателям и их руководителям, менеджерам продуктов и проектов, тимлидам и архитекторам, CTO, энтузиастам свободного программного обеспечения.

Технологии и ключевые слова: reStructuredText, Sphinx, Markdown, Jekyll, Git, CI/CD, GitLab CI, Docker, pandoc.

Обзорный доклад о том, какую техническую информацию можно подавать в формате видео и каких основных правил следует придерживаться для получения качественной видеодокументации.