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

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

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

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

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

Материалы Мини-Гипербатона про документацию в 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

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

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

8 комментариев
Санкт-Петербург,техписатель,сообщество,семинары,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 комментария
Доквариумы: онлайн-встречи технических писателей от ПроТекст
ПроТекст
2 декабря 2016, 09:39

Мы, компания «ПроТекст» (https://protext.su/), хотим поделиться с вами полезной информацией :)

Летом мы начали проводить встречи для технических писателей в формате бесплатных вебинаров – Доквариумы. Каждый Доквариум посвящён определённой теме, в программе – 2-3 доклада, ответы экспертов на вопросы участников и обсуждение любых вопросов по теме. Онлайн-формат позволяет полноценно участвовать докладчикам и слушателям из любых городов.

На данный момент прошло две встречи, все желающие могут посмотреть их в записи:

Записи других мероприятий, которые мы проводили, можно увидеть на нашем сайте в разделе «Конференции».

Приглашаем вас на третий Доквариум, который предположительно будет посвящён теме скриншотов и пройдёт в конце января или начале февраля. Мы планируем проводить такие встречи периодически – предлагайте темы, которые для вас актуальны, по адресу info@protext.su, мы учтём пожелания! А если вы хотите стать докладчиком на очередном Доквариуме - тоже смело пишите нам, мы приветствуем любую активность:)

Нет комментариев
конференция
Мини-Гипербатон. Открыта регистрация
Юрий
24 ноября 2016, 13:55

Всем привет,

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

Мини-Гипербатон состоится 12 декабря в Санкт-Петербурге и 13 декабря в Москве.

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

В  программе два доклада и неформальная дискуссия с участниками встречи. Специалисты из Яндекса будут рады ответить на ваши вопросы и узнать о вашем опыте.

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

Для всех, кто не сможет присутствовать, позднее мы выложим видеозаписи докладов.

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

11 комментариев
мини-гипербатон,яндекс,конференция,2016
DocFactor: конференция о технической документации в Новосибирске
Семён Факторович
27 октября 2016, 17:35

Впечатлившись масштабом Яндекс.Гипербатона я решил, что здорово сделать что-нибудь похожее в родном городе.

Итак, встречайте: 

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

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

Наши доклады:

  • Михаил Острогорский (Philosoft, Москва) расскажет об официально утвержденном российском профессиональном стандарте «Технический писатель»,
  • Ольга Кириченко (UNIGINE, Томск) сделает доклад о карьере технического писателя и процессах документирования на примере своей компании
  • Семён Факторович (documentat.io, Новосибирск) поделится опытом в области поиска, отбора и собеседования технических писателей
  • Дмитрий Лишик (Сигнатек, Новосибирск) расскажет о системном подходе к техническим коммуникациям
  • Павел Семёнов (Сбертех, Новосибирск) расскажет о принципе единого источника и об инструментарии для его реализации

Место проведения: Новосибирск, Академгородок, новый корпус НГУ (ул. Пирогова, д.1).

Дата и время: 4 ноября 2016, 10:00-18:00.

Участие бесплатное, но всем желающим поучаствовать необходимо зарегистрироваться на сайте конференции (http://docfactor.ru)

Если вы живете далеко от Новосибирска (или не готовы потратить целый выходной день на участие в конференции), к вашим услугам онлайн-трансляция.

До встречи!

Нет комментариев
Как правильно описывать последовательность шагов?
Кирилл Богатов
11 октября 2016, 09:07

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

Ситуация такая: пользователь переходит в один из разделов меню и должен заполнить форму регистрации. Есть несколько вариантов того, как можно описать это:

Первый вариант:
1. Нажмите Отгрузить услугу > Выбрать услугу. Откроется страница с параметрами отгрузки.
2. Заполните поля формы.

Второй вариант:
1. Нажмите Отгрузить услугу > Выбрать услугу.
2. На странице Отгрузка услуги заполните поля формы.

Третий вариант:
1. Нажмите Отгрузить услугу > Выбрать услугу.
2. Заполните поля формы.


Какой вариант вы считаете наиболее удачным?

 

4 комментария
вопросы,руководство пользователя