Клуб технических писателей

Клуб для общения технических писателей на профессиональные темы.
Делитесь в клубе своими методиками и подходами, интересными статьями и исследованиями о техническом документировании, анонсами конференций.
Задавайте вопросы коллегам и помогайте советами другим.
Приветствуются публикации на следующие темы:

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

Конференция для технических писателей Гипербатон.

Чтобы подписаться на уведомления о публикациях в клубе, перейдите по ссылке.

Мини-Гипербатон про DITA. Регистрация открыта
Юрий
28 ноября, 11:20

Мини-Гипербатон про технологию DITA

Добрый день, 

Рады сообщить, что опубликована программа и открыта регистрация на Мини-Гипербатон, посвященный технологии DITA. 

Участие в конференции бесплатное, но необходимо зарегистрироваться.

Мини-Гипербатон — камерное мероприятие для обмена опытом на заданную тему с упором на живое общение, рассчитанное на небольшое количество участников. Чтобы встреча прошла наиболее продуктивно, отбор проводится с учетом опыта и интересов зарегистрировавшихся. После мероприятия мы выложим видеозаписи докладов.

Нет комментариев
Мини-Гипербатон про DITA. Анонс мероприятия
Юрий
24 ноября, 12:00

Всем привет, 

Мини-Гипербатон про технологию DITAРады сообщить, что 11 декабря в Москве и 13 декабря в Санкт-Петербурге состоится Мини-Гипербатон, посвященный технологии DITA. Докладчики расскажут об автоматизации редактуры, адаптации готовых шаблонов, изменении языка разметки, а также информационной архитектуре и подходах к проектированию технической документации. 

Программу мероприятия и открытие регистрации мы анонсируем дополнительно.

Напоминаем, что Мини-Гипербатон — камерное мероприятие для обмена опытом на заданную тему с упором на живое общение, рассчитанное на небольшое количество участников.  Для всех, кто не сможет присутствовать, мы выложим видеозаписи докладов.

4 комментария
мини-гипербатон,Яндекс,конференция,2017
DocFactor'17: новосибирская конференция о технической документации
Семён Факторович
21 ноября, 13:13

26 ноября в Новосибирске пройдет конференция о технической документации DocFactor.

Доклады:

Стоп! Снято! Видео в технической документации (Павел Семенов, Сбертех, Новосибирск) 

Поддержка поддержки. Как настраивать процессы документирования в условиях полного цикла выпуска «железа» (Константин Медведев, Тион, Новосибирск) 

Оценка трудозатрат и сроков документирования (Александр Лебедев, Философт, Москва) 

Документация как код в промышленных масштабах (Николай Волынкин, Plesk, Новосибирск) 

Из чего же сделаны наши стайлгайды (Семён Факторович, documentat.io, Новосибирск) 

С той стороны зеркального стекла: взгляд на документацию с точки зрения бизнеса (Максим Строев, HDsoft/Zodiac Interactive, Новосибирск) 

Системный подход к организации процессов документирования в продуктовой ИТ-компании (Виктория Кондрашук, Финансовые информационные системы, Новосибирск)

Мой заказчик — война. Парадоксы и лайфхаки разработки документации для военных (Леонид Станкевич, UNISCAN RESEARCH, Новосибирск)

Участие в конференции бесплатное, для зарегистрировавшихся участников будет организована онлайн-трансляция.

Сайт конференции: http://docfactor.ru

Регистрация: http://docfactor.ru/register

Нет комментариев
Видео выступлений с докладами секции Technical Documentation and Communication на конференции SECR-2017
eduard-tibet
16 ноября, 15:04

Список приведен в хронологическом порядке выступлений. Программа: http://2017.secr.ru/lang/ru/program/agenda

20.10.17

Управление знаниями в “Лаборатории Касперского” http://0x1.tv/20171020DK

Контент для пользователя — битва за эффективность http://0x1.tv/20171020DL

Документация как код в промышленных масштабах http://0x1.tv/20171020DM

Confluence и collaborative documentation — возможности и подводные камни http://0x1.tv/20171020DN

21.10.17

Документация — что может пойти не так. Типичные сложности и подводные камни http://0x1.tv/20171021DF

Как найти, настроить и внедрить техписателя http://0x1.tv/20171021DG

Единый источник в документации — подходит вашей команде или нет? http://0x1.tv/20171021DH

От Knowledge Acquisition к Knowledge Management http://0x1.tv/20171021DI

Автоматизация оценки качества пользовательского контента http://0x1.tv/20171021DJ

1 комментарий
Материалы Мини-Гипербатона про документацию в Markdown
Юрий
10 октября, 12:00

Мини-Гипербатон про Markdown 15 сентября 2017 года15 сентября мы провели Мини-Гипербатон, посвященный документированию в Markdown. Мероприятие проходило в Москве. В камерной обстановке докладчики поделились своими секретами ведения документации в MD. 

Рады сообщить, что материалы с конференции опубликованы.

Видео

Фотографии

Нет комментариев
Яндекс,мини-гипербатон,конференция,2017
Мини-Гипербатон. Регистрация открыта
Юрий
30 августа, 12:10

Мини-Гипербатон 15 сентябряДобрый день,

С радостью сообщаем, что опубликована программа и открыта регистрация на Мини-Гипербатон, посвященный документированию с помощью Markdown.

Участие в конференции бесплатное, но необходимо зарегистрироваться. Регистрация закрывается 12 сентября в 18:00 по московскому времени.  Количество мест ограничено.

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

Да пребудет с вами Сила!

4 комментария
конференция,мини-гипербатон,Яндекс,2017
Мини-Гипербатон. Анонс мероприятия
Юрий
23 августа, 14:50

Всем привет,Мини-Гипербатон 15 сентября

15 сентября в московском офисе Яндекса состоится Мини-Гипербатон. Докладчики осветят особенности использования Markdown для подготовки текстов, а также поделятся рецептами приготовления красивой документации из этого формата. Программу мероприятия и открытие регистрации мы анонсируем дополнительно.

Напоминаем, что Мини-Гипербатон — камерное мероприятие для обмена опытом на заданную тему, рассчитанное на небольшое количество участников.  Для всех, кто не сможет присутствовать, мы выложим видеозаписи докладов.

3 комментария
мини-гипербатон,Яндекс,конференция,2017
OpenAPI
Konstantin Savenkov
3 августа, 07:58

Привет. 

Так получилось, что мы (https://inten.to) занимаемся интеграцией большого количества API. Это удобно, когда у API есть понятная и структурированная документация. За последние год-полтора довольно много компаний переходят на OpenAPI (в прошлом Swagger, https://www.openapis.org), вокруг которого собрался неплохой консорцим (https://www.openapis.org/membership/members). Мы там, наверное, единственная из условно российских компаний. 

К сожалению, в России стандарт распространен довольно слабо.

Мы можем на каком-нибудь из митапов/конференций (например, Гипербатон) рассказать про OpenAPI - как появился, зачем, какие вокруг стандарта есть инструментальные средства, куда это все двигается итп.

Интересно?

4 комментария
Тест-драйв поддержки форматов Help+Manual и DITA
doroninpavel
3 августа, 07:36

Коллеги, привет!

Недавно мы в Smartcat сделали поддержку двух техписательских форматов: DITA и XML-топики Help+Manual.

Среди вас совершенно точно есть поклонники DITA  и, возможно, пользователи Help+Manual. Я надеюсь, у кого-нибудь найдётся время и желание протестировать поддержку этих форматов в Smartcat  и поделиться фидбеком.

Мы попробовали разобраться сами и сделать возможность переводить топики в Smartcat удобным способом, но нам не хватает опыта работы с DITA, поэтому сами мы оценить не сможем.

Если кто-нибудь из вас дочитал до этого абзаца и заинтересовался, напишите мне на p.doronin@smartcat.ai.

Паша

Нет комментариев
перевод,локализация,dita,help+manual,smartcat
Карта "World of Technical Communication"
Кристина
21 июня, 20:30

Сара Мэддокс, техписатель из Сиднея, с 2014 года самостоятельно строит и заполняет карту мира техдокументации:

Ссылка на карту: http://sarahmaddox.github.io/techcomm-map/ 

Статья на сайте Сары: Introducing Tech Comm on a Map

Нет комментариев
мир техписателей,карта техписателей,интересное
Структура базы знаний
Кирилл Богатов
22 мая, 17:27

Здравствуйте, коллеги!

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

Например, есть описание справочника. Технический специалист хочет знать о том, как этот справочник связан с другими объектами и настройками, какие нюансы есть в его заполнении.  Для обычного же пользователя этот справочник — лишь один шаг в решении задачи.

Мешать техническое и пользовательское описание нельзя, но и усложнять структуру тоже не хочется. Пока что склоняюсь к такому варианту:

  • Главная страница
    • Общая тема
      • Инструкция 1
      • Инструкция 2
        • Шаг 1
        • Шаг 2
      • Решение проблем
      • Технические нюансы
        • Справочник 1
        • Справочник 2

Беда в том,  что связь конкретного справочника с общей темой не всегда очевидна. А значит, читателю будет тяжело найти нужную статью.

Что вы думаете о такой структуре? Как можно сделать лучше?

6 комментариев
структура
Программа пятого Гипербатона
Юрий
16 мая, 12:00

Добрый день,

Опубликована программа пятого Гипербатона, который состоится 3 июня в Москве.

Докладчиками на конференции выступят сотрудники Яндекса, Лаборатории Касперского, Positive Technologies и Сигнатек.

Напоминаем, что участие в конференции бесплатное, но необходимо зарегистрироваться. Регистрация закрывается 29 мая в 16:00 по московскому времени.

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

Да пребудет с вами Сила!

8 комментариев
гипербатон,конференция,2017,яндекс
Пятый Гипербатон. Регистрация открыта
Юрий
5 мая, 12:30

Добрый день,

С радостью сообщаем, что открылась регистрация на пятый Гипербатон.

Мероприятие состоится 3 июня в московском офисе Яндекса. Также можно присоединиться к  онлайн-трансляции.

Участие бесплатное, количество мест ограничено.

С этого года Гипербатон проводится в расширенном формате. Теперь это — профильная конференция по вопросам разработки документации и локализации контента.

Гостей ждут тематические секции:
- Документирование
- Локализация
- Инструментарий

Программу конференции анонсируем позже.

Да пребудет с вами Сила!

4 комментария
гипербатон,2017,конференция,яндекс
Выбор вики-движка
Великолепный Сеня
13 апреля, 12:14

Коллеги, доброго времени суток. Я работаю в компании, где пользовательская документация хранится в PDF файлах. Сейчас встал вопрос о переносе всей документации на вики-движок. Подскажите годные бесплатные варианты вики-движков. Спасибо.

2 комментария
Академия Гипербатона — новый учебный проект для начинающих техписаталей
Анастасия
21 марта, 12:12

Мы давно задумали учебный проект для начинающих специалистов в области разработки документации. И вот, свершилось: этой весной стартует Академия Гипербатона. Курс состоит из нескольких мастер-классов:

Процесс документирования
Подробно обо всех этапах создания документации: генеральная линия и маленькие хитрости. Что нужно узнать заранее, как общаться с заказчиками и консультантами, как отшлифовать текст.

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

Способы редактирования и маркеры проблемного текста
Какие формальные и смысловые признаки покажут, что текст небезупречен. Три способа улучшить стиль. Как найти и обезвредить неточную мысль — ищем маркеры проблемного текста. Потренируемся на актуальных примерах из Яндекса и не только.

Схемы в документации: теория и практика
Зачем нужны схемы в документации, какие они бывают и чем хорошая схема отличается от плохой. Как сделать схему с нуля: пошаговая работа в рамках практических заданий. Использование Microsoft Visio при работе со схемами и их отдельными элементами.

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

Для поступления нужно пройти тестовое задание. Регистрация закроется 27 марта в 20:00. Результаты будут объявлены 6 апреля.

Желаем удачи!

5 комментариев
VII встреча Сообщества технических писателей Санкт-Петербурга - 22 марта 2017
Salangin
20 марта, 07:48

Сообщество технических писателей Санкт-Петербурга приглашает на VII встречу

22 марта 2017, среда, 19-21ч, SEMrush

Тема митапа: SEO для технических писателей (доклад Елены Терентьевой — Product Marketing Manager, SEMrush), а также обсуждение использования Medium

Коллеги, скоро день весеннего равноденствия — хороший повод начать что-то новое. Приглашаем вас встретиться в SEMrush и поговорить о SEO 22 марта, в среду.

Технические писатели привыкли писать сложные технические тексты для внутренненго использования. Для них зачастую неважно мнение читателя, у них нет цели продать продукт или продвинуть сервис. Но времена меняются, и многие небольшие компании отказываются от услуг классических техписателей. Сейчас техрайтеры должны расширять свой кругозор, получать новые знания и вырабатывать навыки, чтобы не остаться на обочине IT-мира.

Нам в этом поможет Елена Терентьева, Product Marketing Manager компании SEMrush. Елена специализируется на продвижении продуктов, связанных с техническим SEO. Последние восемь лет занимается маркетингом и PR. В портфолио Елены — публикации в крупных российских бизнес-изданиях: Коммерсант, Ведомости, РБК, а также в зарубежных: Entrepreneur, HubSpot, Search Engine Journal, Search Engine Watch

В программе:

  • 19:00 — Medium как траплин для техрайтера — дискуссия, модератор Станислав Салангин  (SPb Techwriters)
  • 19:30 — SEO для технических писателей: шаг за шагом — доклад Елены Терентьевой
  • 20:30 — обсуждение доклада. Также у вас будет возможность получить рекомендации по профессиональному развитию, поделиться своими проблемами, обсудить ситуацию на рынке труда и поспорить о роли техрайтеров в меняющемся мире IT

Мы обсудим вопросы:

  • основы поисковой оптимизации (видимость в сети, позиционирование контента в поисковых системах, органический трафик, зависимость трафика от контента, взаимодействие с поисковиками и расширение аудитории)
  • привлечение читателей (источники интернет-трафика, целевой трафик, исследование ключевых слов)
  • оптимизация материала (контент, структура, время ожидания, дизайн)
  • внешнее SEO (гостевой блогинг, комментирование, ссылки в Википедии, социальные закладки
  • черное и белое SEO
  • анализ эффективности SEO

Вся информация и регистрация:

Наши партнеры:

9 комментариев
Санкт-Петербург,техписатель,сообщество,семинары,SEO,контент,митап
ProКонтент 2.0 — Ближе к пользователю
Александр Н
1 марта, 07:41

Год назад в "Лаборатории Касперского" прошла первая встреча ProКонтент для технических писателей, переводчиков и локализаторов. Мы рассказали о документировании всем известных истин, проектировании интерфейсов, силе текста и контроле его качества.

Познакомиться с материалами первой конференции ProКонтент можно в этом плейлисте.

16 марта мы вновь приглашаем в "Лабораторию" всех желающих, чтобы поделиться секретами, услышать ваши вопросы и поговорить о том, что нас объединяет — о контенте.

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

Подробности встречи и регистрация на событие:

https://events.kaspersky.com/event/procontent2

Мероприятия "Лаборатории Касперского" бесплатны к посещению при условии предварительной регистрации.

1 комментарий
конференция,мероприятия
Февральская встреча Сообщества технических писателей Санкт-Петербурга - 10 февраля 2017
Salangin
6 февраля, 07:59

Пятница, 10 февраля 2017, SEMrush, с 19 до 21 ч. Приглашаем на очередную встречу технических писателей. Основная тема — Документация в мобильной разработке. Кроме того, в ходе Lean cafe техрайтеры нашего города расскажут о своих достижениях, поделятся секретами и обменяются опытом.

Коллеги, наступил февраль, а с ним и День технического писателя — 2 февраля. Пришлашаем вас встретиться в SEMrush и поздравить друг друга 10 февраля, в пятницу.

В программе:

  • Lean Cafe «Знакомство, новости, ресурсы» (с 19 ч.)
  • Перерыв (у вас будет возможность получить рекомендации по профессиональному развитию, поделиться своими проблемами, обсудить ситуацию на трудовом рынке и поспорить о роли писателей в меняющемся мире IT)
  • Круглый стол «Документация в мобильной разработке» (с 20 ч.). Мы обсудим вопросы:
    • Какие новые термины должен знать техрайтер?
    • Необходимо ли техническое задание на мобильное приложение?
    • Каким может быть туториал в мобильном приложении?
    • Что писать в справке о приложении?
    • Будут ли пользователи читать сопроводительную документацию?
    • Как организовать пополнение FAQ?
    • Где найти информацию о разработке для iOS и Android?

Мероприятие бесплатное. Печеньки, чай и кофе — для вас.

Инфо и регистрация:
— на Timepad.ru: https://tw.timepad.ru/event/441497 
— на Meetup.com: http://meetu.ps/368fQ5 и приходите в любое время с 19 до 21.

Где: SEMrush, станция метро «Ладожская», улица Якорная, дом 7, БЦ «Анкор»

Как доехать: доехать до метро «Ладожская», выйти и повернуть налево, пройти 270 м до остановки трансфера SEMrush (микроавтобус с табличкой «SEMrush» на боковой двери).
Остановка трансфера находится: угол Гранитной улицы и Уткина переулка (около стрительного забора).
Автобус отправляется каждые 20-25 минут, начиная с 18 ч. (18-00, 18-20 и далее).

По всем вопросам звоните мне, Станиславу Салангину: +7(911)958-18-21 
или пишите в наши группы в соцсетях:

Следите за новостями в наших группах!

О Сообществе технических писателей Санкт-Петербурга:

Цель сообщества — создание и развитие открытой среды для профессионального общения, обмена опытом и роста. Сообщество работает в Санкт-Петербурге четвертый год. Его члены принимают участие в IT Global Meetup-ах, конференциях «Гипербатон». Организуются встречи с другими IT-сообществами. Приглашаем вступать в наши группы в соцсетях, участвовать в наших встречах, выступать на митапах.

2 комментария
Санкт-Петербург,СПб,техписатель,обмен знаниями,обучение,События,мобильные приложения,семинары,сообщество
О слове «требуемый»
Кирилл Богатов
6 февраля, 07:59

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

Введите требуемое значение параметра.


Контекст
Многие думают, что если убрать слово «требуемый», то пользователи начнут вводить всё подряд. На самом деле, нет.

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

Возьмем какую-нибудь часть мануала и «развернем» её с учетом контекста:


Введите требуемое значение параметра в поле «Количество».

Чтобы оформить заказ, укажите количество товара. Для этого введите требуемое значение параметра в поле «Количество». Не пытайтесь вводить в это поле свои инициалы или дату рождения, т. к. это приведет к ошибкам в отчете.

Похоже на инструкцию для умственно отсталых.

В контексте задачи все значения являются требуемыми. Разумеется, если не сказано обратное:

Введите соответствующее значение из Таблицы 1.
Введите произвольное значение.


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

В настоящее время я еду в маршрутке.

Я еду в маршрутке.


Чем заменить
Если просто выкинуть слово «требуемый», предложение получается коротким и обрубленным:

Введите значение в поле «Количество».


Чтобы сделать предложение более плавным, его можно  перефразировать или уточнить:

Заполните поле «Количество».
В поле «Количество» введите количество товара в учетных единицах измерения.

Слово «требуемый»  не является уточнением:

— Введите значение.
— Какое значение?
— Требуемое.
— А какое значение мне требуется?
— Количество товара.


Введите количество товара.


А как вы относитесь к слову «требуемый»? Сталкиваетесь ли с другими стоп-словами?

3 комментария
стиль
Итоги первого Мини-Гипербатона
Юрий
28 декабря 2016, 17:00

12 и 13 декабря мы провели Мини-Гипербатон — камерное мероприятие для технических писателей с большим опытом работы в области документирования.

Почему мини?

С 2014 года мы регулярно проводим большую конференцию о разработке технической документации — Гипербатон. Три мероприятия прошли в стенах Яндекса, один раз мы провели секцию в рамках Translation Forum Russia.

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

Наши гости просили устраивать мероприятия чаще, а мы хотели обменяться знаниями с опытными коллегами. На четвертом Гипербатоне мы анонсировали, что попробуем воплотить это в новом для нас формате — митапах. 

Данный вид мероприятия мы назвали Мини-Гипербатоном, а его ключевыми отличиями от большой конференции стали:

  • Приглашение только технических писателей, преимущественно — с большим опытом работы.
  • Фокус на одной тематике.
  • Упор на живом общении и обмене опытом.

Мероприятие поочередно прошло в двух городах — Санкт-Петербурге и Москве, а программа первого Мини-Гипербатона была посвящена работе с текстом.

Что дальше?

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

Материалы
Видео докладов уже доступно по ссылкам:

Да пребудет с вами сила!

3 комментария