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

май 2015
Инструкция по написанию постановки
maria.voronyuk
13 мая 2015, 12:19

Здравствуйте коллеги! Возникла необходимость написать некую инструкцию по созданию/написанию постановки задачи. Необходимо чтобы постановка была понятна и программисту и руководителю и юристу и т.д. Хочу узнать есть ли в Вашей организации подобные инструкции написания документа, если есть хочу обсудить с Вами, с чего начать? что учесть? как вообще к вопросу подойти по созданию инcтрукции? 

На сегодняшний день выделяю несколько основных пунктов, которые должны быть в постановке:

  • общее описание вопроса/проблемы
  • где потребуются изменения (в программном обеспечении, в бизнес-объекте, в базе данных и т.п.)
  • как работает сейчас*
  • как должно работать после изменений* 
  • техническая часть (что конкретно разработчик должен добавить в ПО, БО, БД и т.д)
  • технологическая часть 
  • примеры расчётов* (или любые другие примеры)
  • приложения
* - данных пунктов может не быть, зависит от поступившей задачи.
4 комментария
Структура единого источника
bryston
13 мая 2015, 12:19

В некоторых задачах имеет смысл использовать как пользовательский, так и проектный контент.

Понимаю, что, скажем, содержание технического задания или устава IT-проекта скорее всего НЕ подойдет для руководства пользователя или руководства администратора, но вот, например, для руководства программиста — возможно!

Под единым источником я понимаю структурное хранилище единиц документации в той или иной форме: ядро проекта, файлы XML (для DocBook или H&M), заготовки в MS Word и т. д.

Что может быть единым (использоваться и там, и здесь):

1. Для данной задачи, скорее всего, подойдет единая терминология проекта, которая может из проектной документации "перекочевать" в пользовательскую.

2. Перечень функций, описанных в техническом задании, может "перейти", например, в руководство программиста, а затем — при незначительных правках или фильтрации контента — в итоговое руководство.

3. Описание полей таблиц — в приложения соответствующих руководств или в контекстную справку.

4. Перечень ответственных с их задачами и обязанностями — в технологическую инструкцию и т. д.

Насколько на Ваш взгляд оправданы затраты на такое "совместное" использование контента; если кто-то уже использует подобное решение, не могли бы поделиться опытом?

Заранее спасибо!

10 комментариев
Редактирование внутрь и редактирование наружу
Андрей Пшеничнов
13 мая 2015, 12:19

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

Мне ужасно любопытно, почему так и когда какой подход лучше. 

Объясню свою позицию. Я хочу получить "говорящее" оглавление. Такое, чтобы читатель сразу замапил свой вопрос на нужный раздел, чтобы он сразу выбрал из 5 глав нужную, из 7 разделов выбранной главы нужный. Чтобы это сделать, приходится залезать и в сами разделы, устранять противоречия, которые возникают при изменении структуры. Но это погружение я делаю выборочно, туда, где эти противоречия возникают.

Это моё правило "20-80": на говорящее оглавление я трачу 20% времени и получаю 80% результата. При хорошем оглавлении пользователь точно оказывается в нужном разделе. Да, он потратит время на то, чтобы расшифровать нерафинированный текст. Но он будет уверен, что он приземлился куда нужно, и продраться через текст стоит, ответ на вопрос именно тут. При плохом оглавлении материал будет демотивирующий. Пользователь будет скакать по документу со своим вопросом и читать отлично написанные разделы, которые ему не нужны.

Вторая причина начинать от уровня структуры: представьте себе, что вы двигаетесь "от мелочей" и на уровне структуры понимаете, что материал требует переработки. Тогда часть работы, выполненной раньше, вам придется выкинуть на помойку: некоторые разделы исчезнут, некоторые изменятся до неузнаваемости.

 

Тексты, с которыми я работаю - это пользовательские руководства, обзоры и т.п. Документы с общей логикой изложения, отражающейся в структуре. Если бы я работал с большим количеством несвязанных страниц (например, с контекстными подсказками), вариант Ильяхова мне бы идеально подошёл.

Коллеги, а как обычно редактируете вы? Когда, вы делаете акцент на движении от структуры, когда - от частностей?

 

Андрей Пшеничнов,

ведущий технический писатель

ОАО "ИнфоТеКС"

16 комментариев
«Наставничество как саморазвитие» в текстовом варианте
Алексей
13 мая 2015, 18:16

На апрельском Гипербатоне я рассказал о том, как прошло мое первое наставничество, и что мне с него было. Скачать презентацию и посмотреть видео можно здесь: https://events.yandex.ru/lib/talks/2841/

 

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


Зачем нужен наставник

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

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

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

Что оценивать:

  1. Качество документов. Даже если их еще нет и близко, можно посмотреть на процесс работы поближе, разбить его на внятные шаги (определить ЦА и назначение документа, собрать информацию, структурировать ее и т. д.) и оценивать артефакты отдельных шагов.
  2. Навыки общения с людьми. Технические писатели по долгу службы общаются с огромным количеством людей и изначально неверный подход в этом плане может стоить очень дорого.
  3. Навыки использования инструментов. Программы и технологии, которые использует писатель, должны занимать как можно меньше места в голове, чтобы для собственно документирования осталось побольше.
Как оценивать качество документов — это большая тема. Основные критерии содержательности, полноты и понятности можно трактовать по-разному, я на этом подробно не останавливаюсь.
А навыки общения с инструментами и людьми я в конце концов оценивал по одной шкале, шкале уверенности. Конечно, уверенность трудно измерить, но можно ориентироваться на полюса: человек слишком уверенный в своих силах напортачит с инструментами и людьми, а неуверенный не сможет толком сам делать свою работу.

Зачем нужен наставник разобрались, теперь самое интересное — что же ему за это будет.


Зачем нужен стажер

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

Само не работает

Чтобы получить от наставничества все, что оно может дать, придется напрячься:
  • Слушайте. Работайте с людьми так, как будто вы вместе уже много лет. Мнение новичка, может быть, реже оказывается полезным, но уважать его обязательно нужно.
  • Говорите. Без обратной связи никакого наставничества не будет. Хвалите, предлагайте, подсказывайте. Иначе не будет команды из двух человек, а только два человека, работающие по отдельности над своими KPI.
  • Адаптируйте среду к человеку. Работа стажера — адаптироваться к среде, но если можно что-то сделать в обратном направлении, это стоит делать: новый человек должен как можно скорее считать себя профессионалом таким же, как все остальные, не чувствуя себя меньшинством в каком бы то ни было смысле.

 

Нет комментариев
яндекс,гипербатон
Глоссарий
Ann V.
14 мая 2015, 15:49

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

На Гипербатоне в докладе по стилю документации публике был продемонстрирован кусочек Глоссария - справочника по употреблению терминов с комментариями. На вопросы из студии а не планируется ли выложить этот Глоссарий в открытый доступ, докладчик (Татьяна Грачева) сказала, что это есть в планах и, наверное, произойдет в ближайшем будущем.

 

Так вот, хотелось бы узнать, когда Глоссарий будет опубликован

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

 

 

 

7 комментариев
Проверка документов
Юлия Кухмай
15 мая 2015, 17:10

Привет!

Уважаемые писатели Яндекса и другие DITA-писатели! Поделитесь, пожалуйста, опытом

Как у вас решен технический вопрос проверки документов другими специалистами (аналитиками, программистами, тестировщиками и т.д.).

  1. В каком формате вы отдаете документ на проверку? Или ваши коллеги читают документы в таком же DITA-редакторе?
  2. Когда вы правите документ, включаете ли режим Track Changes, чтобы коллегам было видно, что изменилось? Видно ли это в выходных форматах?
Про себя могу сказать: выгоняем в pdf, в pdf проверяющие вносят комментарии, а мы исправляем в топиках. В итоге нет связанного цикла изменили-прокомментировали-поправили. Каждый раз как с чистого листа.
В нашем редакторе (Oxygen XML Author) есть режим Track Changes и комментариев, но работает он только внутри топиков. На выходе изменений не видно.

Спасибо за ваши ответы!
3 комментария
Вакансия для технических писателей
slonopotamia
15 мая 2015, 17:16

Всем привет!

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

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

У нас здорово и интересно: новые технологии, замечательные коллеги и печеньки на кофепоинтах. Присоединяйтесь к нам!

3 комментария
яндекс,вакансия
Управление одинаковыми определениями
bryston
21 мая 2015, 11:13

Коллеги, кто сталкивается с описанной далее ситуацией, и как Вы ее решаете?

Расшифровка полей таблицы:

Поле | Определение

Клиент | Название клиента.

Клиент | Наименование клиента.

Клиент | Другая сторона в договоре.

Клиент | Контрагент.

Клиент | Юридическое лицо.

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

Можно как-то облегчить или автоматизировать данный процесс?

Пользователи DITA такой механизм имеют, а остальные?

Заранее спасибо!

4 комментария
Связность предложений
Алексей
22 мая 2015, 17:47

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

Предыдущие уроки стиля были сосредоточены на структуре предложений. Но элегантность отдельных предложений вовсе не гарантирует связность абзаца, который они составляют.
Впечатление связности создается, когда последние слова одного предложения подготавливают читателя к первым словам следующего. Читатель чувствует, что информация течет гладко, от начала к концу. По сути, эта гладкость — главная причина того, что мы используем пассивный залог: он помогает построить предложения так, чтобы читателю было легче переходить между ними.
Здесь можно споткнуться, переходя от первого предложения ко второму:
Ключи, доступные пользователю на клиенте, могут быть также использованы на сервере с помощью эмуляции ssh-agent. Только пользователь, который запросил эмуляцию, получает доступ к соответствующему ssh-agent.
Порция пассивного залога сглаживает этот переход:
Ключи, доступные пользователю на клиентском экземпляре сервисов Skynet, могут также быть использованы на удаленном сервере в виде эмуляции ssh-agent. Соответствующий ssh-agent доступен только тому пользователю, который запросил эмуляцию.
Связность также полагается на «хронологическое» изложение информации: читателю легче воспринимать уже известные факты и концепции перед тем, как приниматься за «новую», незнакомую информацию.
Неизвестный термин сбивает с толку, и только дочитав до конца можно понять о чем речь:
Пароли приложений, которые можно создать на странице управления доступом, позволяют контролировать доступ сторонних приложений к вашему аккаунту.
Правильнее начать с очевидной концепции:
Вы можете контролировать доступ сторонних приложений к вашему аккаунту с помощью паролей приложений. Создавать эти пароли можно на странице управления доступом.
Поэтому:
  • Начинайте предложения с того, что уже знакомо вашим читателям. Можно рассчитывать на то, о чем вы писали раньше, и на некоторые базовые знания целевой аудитории.
  • Заканчивайте предложения информацией, которую читатель не может ожидать.
Если вы долго работаете над какой-то темой, все концепции и теории становятся одинаково знакомыми. Становится сложно понять, что можно считать самим собой разумеющимся, а что может оказаться совершенно новым для вашей аудитории. Старайтесь заранее обрисовать круг знаний читателя, на который можно рассчитывать, — будет легче видеть, когда и насколько вы выходите из этого круга.
Это новый принцип ясности предложений, который можно добавить к описанным ранее:
  1. Главные действующие лица — подлежащие в предложениях.
  2. Важные действия — глаголы-сказуемые.
  3. Известная информация подается перед новой информацией.

 

Этим принципам обычно получается следовать одновременно, но если вам приходится чем-то жертвовать, старайтесь в первую очередь следовать третьему принципу — предоставлять информацию последовательно. Организация информации определяет то, насколько связным текст кажется читателям. А связность текста играет гораздо большую роль для легкости чтения, чем прозрачность отдельных предложений.
9 комментариев
яндекс,стиль
Новая версия стандарта ISO/IEC/IEEE 15289 по документации жизненного цикла информационных систем и программного обеспечения
Виктор Фигурнов
22 мая 2015, 17:48

Сегодня вышла новая версия стандарта ISO/IEC/IEEE 15289:2015 "Системная и программная инженерия. Содержание информационных продуктов процесса жизненного цикла систем и программного обеспечения (документация)". 

Предыдущие версии этого стандарта были выпущены в 2006 и 2011 гг. 

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

Ссылки: 

http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=66422 

https://standards.ieee.org/findstds/standard/15289-2015.html

Нет комментариев
Одинаковые имена для различных ресурсов ИТ-объекта
bryston
28 мая 2015, 11:11

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

Приведу пример для наглядности:

  • Contract_Use.pas — исходный код;
  • Contract_Use.xml — топик с описанием;
  • Contract_Use.png — скриншот формы;
  • Contract_Use.vsd — схема договорных отношений;
  • Contract_Use.docx — текст договора;
  • Contract_Use.xlsx — приложение к договору и т. д.

Вопрос возникает, когда необходимо присвоить имена, например, ОГРН, НДС, МВРН и т. д.; записываете то или иное имя латиницей, например, НДС — NDS или ищете адекватный эквивалент, например, НДС — VAT (Value-Added Tax); если используете последний вариант, какие словари Вам помогают?

4 комментария
"Шедевры" из технической документации
Кристина
29 мая 2015, 15:46

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

    • Номер одного из пунктов в документе технического характера

      2.1.3.1.1.16.1.3.2.1



    • Из руководства разработчика

      Порядок слоев объектов отображения в списке отображения определяет порядок слоев отображения независимо от положения объектов по соответствующим осям.



    • 4 причастных оборота в одном предложении

      Введите авторизационный код, отправленный в SMS на номер, оканчивающийся на ХХХХ, действующий в течение 24 часов, или перейдите по вложенной в SMS ссылке.



А с какими "шедеврами" сталкивались вы в своей практике? Что вы делаете, чтобы избежать таких шедевров в вашей документации / документации вашей компании?

20 комментариев
шедевры