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

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

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

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

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

Февральская встреча Сообщества технических писателей Санкт-Петербурга - 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-сообществами. Приглашаем вступать в наши группы в соцсетях, участвовать в наших встречах, выступать на митапах.

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

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

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


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

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

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


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

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

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

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

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


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

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

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


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

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


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

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

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

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


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


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

1 комментарий
стиль
Итоги первого Мини-Гипербатона
Юрий
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 комментария
вопросы,руководство пользователя
Как избавиться от страдательного залога с помощью зомби
Кирилл Богатов
12 сентября 2016, 16:30

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

Зомби в действии

Вот пример текста:

Запрос координат осуществляется с помощью сервиса геокодирования. Координаты определяются автоматически, на основании текущего местоположения устройства.


Добавляем зомби:

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


Убираем страдательный залог:

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

Почему это работает

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

Вместо зомби можно использовать всё, что угодно: гремлинов, коллег по работе, да хоть хачапури с сыром. Желательно, чтобы слово изменялось по падежам, так нагляднее. Лично я использую слово «пользователи»:

Выгрузка данных осуществляется пользователями в раздеде «Обмен».


Убираем страдательный залог:

Выгрузить данные вы можете в разделе «Обмен».


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

Материалы по теме

2 комментария
личный опыт
"Возможность падения с платформы!"
Кристина
1 августа 2016, 10:13

Всегда, когда вижу такой плакат, меня смущает его текст. Но как его переделать — не знаю. Интересно ваше мнение, коллеги — текст абсолютно корректен или мог бы быть лучше? Как бы вы написали?

13 комментариев
примеры из жизни
Приглашаем технических писателей 23 июля 2016 в Санкт-Петербург на IT Global Meetup #8
Salangin
21 июля 2016, 12:28

Коллеги, Санкт-Петербургское сообщество технических писателей приглашает всех на IT Global Meetup #8, который состоится 23 июля 2016 , в субботу в CПб.

Расписание докладов нашего сообщества:

Пояснения к программе:

- 13:00-13:30 Поток 3
- Информационная архитекура DITA против хаоса в документации 
(Darwin Information Typing Architecture. Промышленный подход к разработке документации на основе принципа единого источника. Метаданные. Преобразование в RTF, PDF,HTML. XML-редактор oXygen. Учебные и справочные ресурсы)
- Станислав Салангин

- 14:00-14:30 Поток 3
- Быстрая разработка технического текста для интернета. Советы лингвиста 
(Особенности написания Web-текстов. Важные детали и несерьезные решения. Тех. писатель поневоле: нюансы адаптации специалиста в незнакомой среде, а также оптимизация поглощения новой информации. Как набраться уверенности в себе и овладеть новыми навыками с минимальными затратами времени и нервов)
- Вячеслав Эскин 

- 17.00-17.40
- Жадный техрайтер: работает в офисе, подрабатывает на стороне, нарабатывает на митапах
(Когда можно работать на стороне. Как искать подработку, кто может быть полезен в этом. Как не дать себя кинуть. Сколько просить за подработку. Сколько нужно работать.)
- Наталья Орлова

- 16.00-16.40
Ингредиенты успеха документации
Наталия Желнова

Участие бесплатное, необходима регистрация: piter-united.ru . Ждём вас!

1 комментарий
обучение,Санкт-Петербург,сообщество,техписатель,мероприятия,обмен знаниями,События,конференция,СПб
Стажировка для технических писателей
Антон
21 июня 2016, 17:00

На недавно завершившемся IV Гипербатоне мы анонсировали первый набор стажеров — технических писателей в Яндекс. Все задуманное удалось, и летней стажировке в отделе документирования и локализации официально дан старт.
 
Мы ищем стажеров сразу в двух городах — в московский и екатеринбургский офисы. В Москве стажировка будет проходить в группе документирования рекламных технологий. Стажеры в Екатеринбурге станут частью команды, разрабатывающей справку к пользовательским сервисам Яндекса.
 
К каждому стажеру будет прикреплен опытный наставник, готовый делиться знаниями и помогать в работе. Стажируясь у нас, вы сможете изнутри увидеть процессы документирования в Яндексе, познакомитесь с новыми технологиями и примете участие в создании справки для самых посещаемых сервисов Рунета.
 
Стажерам выплачивается зарплата.
 
Если вы студент, аспирант или начинающий специалист и хотите попробовать свои силы в профессии технического писателя, заполните заявку на сайте вакансий Яндекса.

До встречи!

Нет комментариев
стажировка,яндекс
Итоги Четвертого Гипербатона
Kate Pozdnysheva
16 июня 2016, 17:00

Всем привет! 

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

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

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

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

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

В каждом городе были представлены стенды, где участники могли задать все интересующие их вопросы специалистам из Яндекса (а в Москве еще и специалистам из Лаборатории Касперского и Семену Факторовичу) и спросить все, что не успели у спикеров (на протяжении всего дня было достаточно сложно выдержать регламент по времени из-за потока вопросов к докладам :)).

Что дальше?

Гипербатон — это крупное событие и площадка, где можно собраться, познакомиться, узнать что-то новое, обменяться опытом. И как раз поэтому так важно собирать не только спикеров из Яндекса, но и из других компаний.

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

Ориентировочно, в начале осени мы будем готовы провести первую встречу. 

Материалы

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

Спасибо всем, кто помог сделать этот день! Да пребудет с вами Сила!

Посмотреть фотографии можно в альбоме на Я.Фотках.

Нет комментариев
Из жизни японских техписателей
Кристина
16 июня 2016, 07:41

Японским техписателям очень повезло с языком:

Вот технический текст, переведенный с японского на русский:

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

А вот как такой текст на самом деле выглядит на японском:

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

И замечательное дополнение к статье в комментариях:

Не помню уже откуда, но по форумам переводчиков давно гуляет пример из инструкции к банке с краской: «Трясти, пока звук “кара-кара” не сменится звуком “кося-кося”».

Источник

1 комментарий
юмор,примеры из жизни
Опубликована программа четвертого Гипербатона
Юрий
12 мая 2016, 12:25

Добрый день, 

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

Конференция разделена на следующие тематические блоки:

  • Документация для разработчиков. 
  • Локализация. 
  • Инструменты.

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

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

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

5 комментариев
гипербатон,2016,яндекс,конференция
Как карьера технического писателя убила во мне писателя-литератора
Кристина
25 апреля 2016, 16:29

Пишущим документацию на английском посвящается.

Источник

2 комментария
юмор
Четвертый Гипербатон. Открыта регистрация
Юрий
22 апреля 2016, 11:15

Добрый день,

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

Как и в прошлом году, будет организован телемост, а конференция пройдет одновременно в Москве, Санкт-Петербурге и Екатеринбурге.

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

Программа конференции и список участников будут опубликованы позже.

Участие бесплатное, но необходимо зарегистрироваться до 17:00 (по московскому времени) 31 мая.

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

3 комментария
гипербатон,2016,конференция,яндекс
Конференция ProКонтент 17 февраля 2016
kakorneev
11 февраля 2016, 11:15

Конференция ProКонтент посвящена вопросам создания контента для пользователей (интерфейсы, обучающий контент, техническая документация и другое).

Специалисты «Лаборатории Касперского» расскажут о разработке интерфейсов, функциях текстов в интерфейсах, создании и контроле обучающего контента, а также о написании и локализации технической документации.

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

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

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

3 комментария
Вакансии для технических писателей
Юрий
30 декабря 2015, 14:07

Всем привет,
Мы ищем специалистов в нашу команду:

Приходите — у нас много интересных задач, возможностей развиваться и делать мир лучше

2 комментария
яндекс,вакансия
Облегченная HDITA без XML
Кристина
30 декабря 2015, 13:55

Любопытный вебинар Майкла Пристли (Michael Priestly), создателя DITA, о перспективной DITA 2.0

 

Если коротко, то DITA стала слишком сложной для обычных людей и, чтобы не терять пользователей, помимо XML DITA (XDITA) в скором будущем мы получим еще и облегченную HTML5 DITA (HDITA), где будет всего около 30 тегов вместо 94. 

И еще немного. Возможно, кому-то будет интересен/полезен обзор «Кто, как и почему использует DITA в 2014?»: The State of DITA in 2014 (в виде презентации на английском).

 

2 комментария
markdown с html
yozhik-ezhi
27 ноября 2015, 14:48

Добрый день!

 

Есть ли в вашем клубе возможность получить совет, задать вопрос - с конкретной проблемой при документировании?

 

Буду рада помощи.

 

Мы пишем статьи в маркдауне.

Мне потребовалось изменить вложенные списки с вида:

1.

   1.

      1.

      2

   2.

   3.

2.

в такой:

1.

   1.1

      1.1.1

      1.1.2      

   1.2

   1.3

2.

Для понимания при описании взаимосвязей между пунктами второй вариант куда лучше.

В markdown поддерживаются html теги. Меня интересует расположение стиля:

  • куда ставить блок <style>?
  • нужно ли прописывать тогда остальные html теги?
  • или можно прописать сразу в открывающем теге <ol>?

 

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