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

апрель 2015
Хранение и учет документации
Екатерина
3 апреля 2015, 15:07

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

 

Хранение

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

Основные преимущества таких систем:

  • хранение всех версий одного и того же документа;
  • возможность возвращаться к более ранним версиям;
  • контроль всех изменений документа.

Для DITA-контента мы используем Subversion (SVN). Пользователи Windows работают с ней через Commandline SVN и TortoiseSVN. Маководы и линуксоиды используют стандартные пакеты своих операционок.


Хранение контента мы организовали по классической схеме.

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

  • trunk — здесь ведется разработка документации, создаются ее новые версии. Это рабочее поле технического писателя.
  • stable — сюда попадают согласованные версии документов из trunk. Никакие изменения в stable не допускаются.

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

 

 

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

Например:

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

С такой структурой каталога документа понятно, где какие файлы искать.

 

 

Пробежимся еще раз — какой профит мы получаем от такой организации хранения:

1. Надежность:

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

Учет

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

С одной стороны. Необходимо иметь всю информацию о документе: кто его писал, кто заказывал, когда была опубликована первая версия или последнее обновление.
С другой стороны. Хочется понимать, какие работы ведутся по документам в данный период времени (создание, актуализация, исправление ошибок, перевод, редактура).
С третьей. Нужно отслеживать загрузку людей по задачам.
 
 
Для учета своих задач мы используем багтрекер Яндекса, а вы можете использовать любой другой (например, JIRA, Pyrus).
 
 
Чтобы было проще ориентироваться в огромном пуле задач, для каждого типа документации (пользовательская справка, руководства разработчиков и внутренняя документация) выделен свой проект. Эти проекты, в свою очередь организованы одинаково.
Для каждого документа есть головная задача типа Task, в которой хранится основная информация о нем:
  • название;
  • ссылка на опубликованную версию;
  • место размещения исходников;
  • заказчик задачи;
  • консультанты.
Исполнителем задачи назначается техписатель, ответственный за этот документ. Все работы (создание, актуализация, исправление ошибок, доработки и пр.) фиксируются в виде подчиненных задач с типом Sub-task, у них тоже есть свои заказчики, консультанты и исполнитель.
Получается, что по типу Task мы всегда видим все документы, публикуемые на конкретном сервисе. Для каждого из них можно посмотреть историю и инициаторов всех изменений, даты публикации. Мы можем строить отчетность по задачам, выполненным конкретным автором или за определенный период. Таким образом, в любой момент можно отследить, что происходит с документацией и теми, кто ее пишет.

В заключение

Еще раз перечислим то, что помогает нам делать хранение и учет документации более удобным:
  • организация репозитория;
  • система учета в багтрекере.
А вы можете брать наши рецепты или придумывать какие-то свои — главное, с помощью них делать хорошую и полезную документацию.

5 комментариев
яндекс,конференция,2014,гипербатон,гипербатон 2014 в Екатеринбурге,тезисы доклада
Курсы технических писателей.
Денис Игрушкин
8 апреля 2015, 16:53

Коллеги, добрый вечер.

Подскажите, пожалуйста, толковые курсы/вебинары для технических писателей.

По работе приходится составлять большое количество технических заданий для конкурсов. 

Спасибо!

4 комментария
Technical Writing 101
Пономарева Вера
8 апреля 2015, 17:27

Всем привет,

В своих предыдущих постах (первом и втором) я рассказала о некоторых фишках, вычитанных в книге Technical Writing 101.
Сегодня хочется резюмировать прочитанное и дать общую характеристику этой книге.

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

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

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


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

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


Одним словом, очень рекомендую начинающим профессиональную карьеру!

Нет комментариев
Technical Writing 101,почитать,яндекс
Блиц-доклады на Гипербатоне
Юрий
10 апреля 2015, 16:34

Уже в следующую субботу, 18 апреля, состоится третий Гипербатон.


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


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


Заявки на блиц-доклады будут собираться в течение конференции во всех городах: Москве, Санкт-Петербурге и Екатеринбурге. Оргкомитет конференции выберет доклады, интересные для большинства участников, и объявит докладчиков в начале интерактивной панели.


На каждый доклад отводится не более 5 минут, будет возможность показывать слайды.


Готовьтесь!

Нет комментариев
гипербатон,2015,конференция
Работа над документом. Часть 1. Сбор сведений
Маргарита
15 апреля 2015, 16:05
Процесс создания документа включает в себя такие этапы, как:
— сбор сведений;
— анализ;
— разработка;
— рецензирование.
В этой статье я расскажу о первом этапе — сборе сведений. Поясню, почему он важен, какую информацию необходимо получить и кто может помочь в этом.

Главное назначение документа — помогать читателю решать необходимые ему задачи. Поэтому, прежде всего, необходимо выяснить:
  1. Целевую аудиторию.
  2. Задачи целевой аудитории.
Также нужно извлечь у заказчика все возможные ресурсы для работы над документом.

Целевая аудитория
Чтобы документ был полезным и востребованным, нужно учитывать потребности и способности его читателей.
Потребности читателей позволяют понять какие особенности и качества объекта необходимо описывать, то есть определяют содержание документа. Например, описанием программного продукта может являться:
— описание его преимуществ и возможностей с целью знакомства и продвижения (для менеджеров проектов);
— инструкцией по использованию (для пользователей продуктом);
— справочником структурных элементов кода (для программистов, поддерживающих работоспособность продукта) и др.
Способности читателя помогают определиться со степенью детализации и контекстом описания. Например, читателями инструкции по заполнению таблиц расписаний могут быть как диспетчер автостанции поселка, так и администратор транспортного сайта. Знание целевой аудитории поможет понять, насколько подробно нужно освещать тот или иной аспект, и значительно сужает круг анализируемой в дальнейшем информации.

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

Ресурсы для работы
Это источники информации для самостоятельного анализа, тестирования и изучения объекта описания. А именно:
  1. Существующее описание объекта (текстовые заметки, аудио- и видео-записи).
  2. Сам объект описания (интерфейс и доступ к нему или исходники программного продукта и среда для его отладки).
  3. Координаты коллег, которые могут помочь с информацией по объекту описания.

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

Заключение
Если вам удалось выяснить цели документа и получить все необходимые средства для дальнейшей работы, можно приступать ко второму этапу — анализу. О нем речь пойдет в следующей моей статье.
14 комментариев
процесс,яндекс
Гипербатон уже завтра!
yndx.galil
17 апреля 2015, 15:53

Добрый день!

Уже завтра состоится «Гипербатон» — конференция для технических писателей. В этот раз мероприятие пройдёт одновременно в Москве, Санкт-Петербурге и Екатеринбурге. Во всех городах встречать гостей будут технические писатели Яндекса. Мы организуем телемост, который свяжет всех участников.

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

Также приглашаем Вас поучаствовать в секции «Инструменты документирования», которая начнётся с блиц-докладов и завершится дискуссией с участием экспертов. Заявку на выступление с докладом можно будет подать во время конференции во всех трёх офисах: в Москве, Санкт-Петербурге и Екатеринбурге. Организаторы выберут наиболее интересные заявки и объявят докладчиков в начале секции. На доклад отводится не более 5 минут.

1796846_773756279311162_4219935138304821108_o.jpg

Открытая онлайн-трансляция для всех желающих

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

Вопросы можно задавать не только в зале

Задавайте нашим докладчикам вопросы в Twitter по хештегу #yadoc и в прямом эфире на сайте трансляции. Самые интересные вопросы будут озвучены, на остальные вопросы мы ответим здесь, в нашем клубе. Приз за лучший вопрос — 100 Гбайт на Яндекс.Диске!

До встречи на Гипербатоне!

7 комментариев
яндекс,гипербатон,2015,конференция
Огромное спасибо за Гипербатон 2015
Salangin
19 апреля 2015, 11:57

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

3 комментария
ГОСТ и Яндекс
Марина Левина
20 апреля 2015, 12:31

Применяете ли вы ГОСТ при документировании своих продуктов ?  Если применяете, то уточните, как именно учитываются требования ГОСТ в вашей документации ?

 

Я не в том разделе оставила публикацию ???... 

8 комментариев
Вопросы по докладу "Построить и научить" (Светлана Каюшина)
alxndr.bnd
20 апреля 2015, 15:32

Добрый день. Спасибо за ваш доклад. Ответьте, пожалуйста, на несколько вопросов:

  1. В докладе говорилось о 300 документах, которые разрабатываются силами технических писателей. Что вы понимаете под документом?
  2. Кто является заказчиком для технических писателей? Как задачи попадают в отдел?
  3. Разработка документов начинается после окончания разработки кода?

Спасибо. 

2 комментария
События,яндекс,гипербатон,2015
Документация для SpeechKit
Марина Левина
21 апреля 2015, 20:03

Добрый день! Вами разработано описание на странице SpeechKit ? Есть еще контент о SpeechKit, кроме того, который представлен на странице? Спасибо. 

4 комментария
Документация на английском языке
bryston
23 апреля 2015, 09:54

Коллеги, возникли следующие вопросы, касающиеся английского языка:

  1. Какие методики используете для проверки профессиональных навыков у переводчиков?
  2. Какие курсы повышения квалификации (если таковые имеют место) посещают переводчики?
  3. Если используете "перекрестный" перевод (глава 1 написана на русском языке, а глава 2 — на английском, затем, соответственно, недостающий перевод надо восполнить), как поступаете в данной ситуации?
  4. На каких переводчиков больше обращаете внимание при отборе кандидатов на замещение вакансий: на литераторов, военных, технарей и т. д.?
  5. Используете ли вы англоязычные стандарты по написанию тех или иных пользовательских документов?

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

10 комментариев
Помогите начать!)
Евгения Сидорова
23 апреля 2015, 09:54

Я начинающий технический писатель, подскажите мне необходимую литературу, информацию, для успешного освоения) с чего начать лучше? Спасибо заранее)

4 комментария
Документировать API начать как
Арина
24 апреля 2015, 17:28

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

На этот раз давайте вспомним доклад Как начать документировать API с прошлогоднего московского Гипербатона.

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

План погружения

1. Изучаем системы контроля версий

SVN, GIT.

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

2. Пробуем среды разработки (IDE)

Для JavaScript API: WebStorm.

Для Java, Objective-C: Intellij IDEA, Android Studio, Xcode.

Достаточно уметь создавать программы класса Hello, world! Сделать самые простые примеры использования API.

3. Подучиваем языки программирования

JavaScript, Java, Objective-C (зависит от API).

Уметь читать код «с листа».

4. Осваиваем генераторы документации из кода

Для JavaScript API: JSDoc.

Для Java, Objective-C: Doxygen.

Выбрать генератор документации из кода и научиться с ним работать.

5. Пишем

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

А пока можно прочитать полную расшифровку записи выступления (под катом, сделано с применением мобильного приложения Яндекс.Диктовка).

Расшифровка

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

Тема моего доклада — как начать документировать API.

Как документировать api я сегодня вам расскажу на своем примере. Я пришла в Яндекс, как уже сказала Света, недавно и как раз чтобы в 1 раз в жизни столкнуться с этой задачей. И сейчас я вам расскажу о своем опыте.

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

Application programming interface называют это американцы. У нас говорят апИ или Апи. API — это интерфейс, который позволяет разработчикам использовать функционал некого программного продукта в своих разработках. Ну например, я хочу использовать Яндекс.Карту на своем сайте, — использую API Яндекс.Карт. У Вконтакте есть APIНа самом деле, API очень много и они разные. Документировать API означает описывать то, что сделали одни разработчики для других разработчиков. Для этого нужно глубокое погружение в технологии. Нужно быть специалистом одновременно и в области документирования. И в области разработки.

Кто может быть таким человеком?

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

 Когда я готовилась к докладу, я нашла пример такого человека. Это Линдсей Скотт, модель victoria secret, которая создает приложения для айфона. В принципе её можно уговорить стать техническим писателем. Тем более как она говорит в интервью в колледже у нее еще есть курс русской литературы. Но такой кандидат это скорее исключение, чем правило. И вы слышали об этом сегодня говорил Кирилл.

 Вот у нас всего 2 примера: Линдси Скотт и Кирилл, у которого филологическое образование. Что же делать?

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

Как документировать API?

Это очень просто. Надо взять непонятный API и превратить его в понятный API. Правда, вот под знаком вопроса там есть некоторые сложности.

Что для этого нужно сделать?

Нужно сначала самому разобраться. А потом задокументировать API так, чтобы он стал понятен и другим разработчикам тоже. Итак, главный секрет я вам сообщила. А теперь давайте посмотрим, как это выглядело на практике.

Итак, API который мне достался, позволяет размещать карты в мобильных приложениях. Физически это библиотека на языках java и objective c. Платформы ios и android. И как же я начала с этим всем разбираться.

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

Для начала меня заставили погрузиться в особенности работы с Unix-подобными системами. Дело в том, что Android и iOS это Unix-подобные операционные системы, Mac OS тоже. А я до этого только Windows использовала. Итак, мне выдали Mac для работы и чуть позже выдали справочник с командами операционной системы Linux, которые я изучала.

Мне, конечно, помогали. Вот руководитель группы на фотке (справа). Он выписал мне команды на листочек, основные, которые я потом выполняла в консоли на скорость. Когда я немного уже освоилась с работой на Маке, с операционной системой, можно было переходить ко второму этапу.

Меня познакомили с технологиями документирования, которые используются в Яндексе.

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

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

Служба документирования в Яндексе использует Subversion или SVN. А разработчики на моем проекте использовали GIT. Когда я научилась работать с системами контроля версий, мне рассказали, что документирование в Яндексе строится по принципу единого источника. В двух словах для меня это выглядело так: документы создаются не в Ворде, который я использовала до этого всё время, а в xml-редакторе с поддержкой DITA.

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

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

Это третья часть моей истории. API.

2 библиотеки, на двух языках, как начинать в этом разбираться?

Мы решили что лучше всего будет начать с примеров использования API и я установила себе среды разработки. Вы сейчас на экране видите логотипы вещей которые я использовала, это Xcode, Intellij IDEA, Android Studio немножко. И попыталась начать писать Хеллоу-ворлды (программы класса Hello, world!). Вот сейчас на экране самый мой популярный запрос в Яндексе в то время: Hello world Android.

Итак, нужно было еще параллельно, конечно, изучать языки. У меня конечно был курс C++ в институте, но это было 10 лет назад и надо было начинать с нуля. Я пошла в библиотеку Яндекса. Сейчас на фотографии вы её видите, взяла несколько книжек. И, вооружившись всем этим, я написала несколько базовых примеров использования нашего API. Конечно, у меня был один пример от разработчиков, вот я с помощью этого примера разобралась в базовых классах и могла уже написать собственное приложение. Оно было простейшее, карта там, несколько меток, но я его сделала.

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

Справочник — это описание всех классов, методов, функций, параметров, всего того, что составляет программный интерфейс. В принципе было понятно как его делать, мы посмотрели на сайтах платформ как выглядят справочники и осталось только сделать такой-же справочник, но для нашего API.

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

Генерация документации из кода. Конечно, справочники такого объема редко создаются вручную. Часто используются специальные программы, генераторы, которые из кода, снабженного документационными комментариями, могут создавать справочники на человеческом языке. Задача эта не новая и в Википедии я нашла табличку со списком из 54 генераторов, которые все вместе охватывают 24 языка программирования. У нас было всего 2 языка: Java и Objective-C.     

Но нам нужен был 1 генератор для них. Мы попробовали, подумали про несколько генераторов, попробовали JavaDoc, который является классическим инструментом для Java, посмотрели HeaderDoc, который часто используется для Objective-C. В итоге мы выбрали Doxygen.

Doxygen мы выбрали по трем причинам. Во-первых он хорошо справляется с языками семейства C и с Java и на самом деле с большим количеством языков. Во-вторых Doxygen довольно гибкий инструмент. У него большое количество настроечных параметров. И третья причина — xml-выход Доксиджена мы могли сравнительно легко преобразовать в нашу Диту. Дело в том, что у большинства автогенераторов основным выходом является html. С этим было бы сложно работать. И мы выбрали Doxygen. Но нам пришлось написать программу, которая преобразует выход Doxygen в нашу DITA.

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

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

Итак, 4 подхода к снаряду у меня было. На большее количество подходов к снаряду меня не хватило, потому что всё оставшееся время я потратила на следующий слайд. Это типовой комплект документации. Про быстрый старт я вам рассказала, про справочник мы поговорили и осталось руководство пользователя. Вот которым я сейчас занимаюсь. Руководство пользователя это полное описание того, как использовать API, с большим количеством примеров, как правило. И здесь еще примеры вынесены в отдельный пункт, потому что часто их действительно выносят в отдельный документ. У нас есть такая история, например, Песочница, и про это вы можете спросить у Миронова Алексея, кстати, на стендах. Итак, это комплект документации. Давайте в завершении кратко повторю что же пришлось освоить, чтобы к этому комплекту подобраться.

Итак. Начали мы погружение с операционных систем. Продолжили средствами разработки.  Системы контроля версий. Языки программирования. Среды разработки. Генераторы документации из кода. Вот такой путь примерно. На самом деле этот путь не уникален. [вырезано немножко]

А закончить я хочу вот чем. Это мое субъективное мнение. Отличие пользовательских интерфейсов от программных. Когда пользователь начинает пользоваться какой-то программкой, он что говорит?  Все плохо спроектировано. Интерфейс не интуитивный. В последнюю очередь человек жалуется на документацию. Чаще всего потому, что документацию он не читал. Ну бывает, конечно, потому что документация хорошая. 

А в случае программмных интерфейсов, когда API выходит в свет, первое, на что начинают жаловаться — это то, что отсутствует документация. Если её конечно нет. Поэтому документация — это не какая-то дополнительная полезная штука. Это неотъемлемая часть API. И документатор в этот момент становится разработчиком API. И на такую задачу можно взять человека без опыта разработки. Он обязательно согласится программировать, а потом втянется и у вас будет хороший специалист на руках. Или на шее. Ну, как посмотреть.

На этом моя история заканчивается.

 

Посмотреть видео доклада 

Скачать презентацию в формате pdf 

2 комментария
яндекс,гипербатон,2014
Единая графика
bryston
27 апреля 2015, 09:55

Добрый день, уважаемые коллеги!

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

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

А вот с форматом — сложнее.

Не секрет, что маркетологам больше подходят картинки в JPG (опять же фотографии хорошего качества с выставок и стендов), техническим специалистам — чем меньше, тем лучше — например, GIF, писателям и переводчикам — PNG (качество без потерь и, наконец, не очень большой объем самого файла картинки), все больше в моду входят векторые форматы графики или, скажем, аналитики работают c форматами бизнес-процессов IDEF, Visio или Arias, которые передаю друг другу схемы, естественно, в "родном" не графическом формате, но эти схемы рано или поздно надо вставлять в документацию...

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

Заранее спасибо за ответы!

8 комментариев
Описание алгоритмов, схемы
alxndr.bnd
29 апреля 2015, 09:21

Добрый день!

Как вы описываете алгоритмы? Используете ли схемы? Или избегаете из?

1 комментарий
схемы,алгоритмы
По следам конференции
yndx.galil
30 апреля 2015, 12:53

Всем привет!

 

G88A9525.jpg

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

 

В этот раз мероприятие прошло одновременно в Москве, Санкт-Петербурге и Екатеринбурге. Мы организовали телемост, который связал всех участников. Мероприятие собрало 130 человек в зале в Москве, 55 в Санкт-Петербурге и 20 в Екатеринбурге. В этот раз мы уделили отдельное внимание организации онлайн-трансляции, нас смотрели 485 человек из более, чем 70 городов 8 стран мира (Россия, Украина, Беларусь, Эстония, Швеция, Германия, Великобритания, Тайланд).


Дополнительные активности

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

G88A9532.jpg

 

Кроме того на конференции работало 3 стенда: 

  • Яндекса, на котором писатели компании демонстрировали используемые инструменты и отвечали на вопросы посетителей.
  • Лаборатории Касперского, где рассказывалось про инструмент Author-it.
  • Моспротекста, на котором демонстрировались возможности технологии DITA.

G88A9729.jpg


Итоги анкетирования

В нашем опросе приняли участие 114 респондентов в Москве, 55 в Санкт-Петербурге (что составляет 100% участников), и 18 в Екатеринбурге. Все участники ответили, что готовы посетить нашу конференцию и в следующий раз. Многие предложили темы для следующего Гипербатона, что не может нас не радовать. Спасибо за вашу инициативность.

 

Все докладчики получили хорошие оценки за выступления, но самыми полезными по результатам анкетирования оказались доклады Максима Ильяхова ("Сильный текст для нелингвистов"), Татьяны Грачёвой ("Руководство по стилю документации: зачем и как") и Дарьи Ерёминой ("Как не утонуть при погружении в Большой проект").

 

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

 

Еще раз большое спасибо всем, кто принял участие в мероприятии. 

Нам было очень приятно видеть вас в зале, читать твиты по хештегу и анкеты обратной связи. Кстати, наш хештег #yadoc находился в топе популярных по Москве на протяжении 5 часов 40 минут.

Снимок экрана 2015-04-23 в 15.27.37.png


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

2 комментария
yadoc,яндекс,гипербатон,2015,конференция