Подготовка технической документации *

Меня зовут Андрей Поляков, я руководитель группы документирования API и SDK в Яндексе. Сегодня я хотел бы поделиться с вами докладом, который я и моя коллега, старший разработчик документации Юлия Пивоварова, прочитали несколько недель назад на шестом Гипербатоне.


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

Осенью 2016 года нам с коллегой поручили улучшить документацию и контент в моей бывшей компании. Мы потратили год на все виды документации: справочник по API, руководства, учебные пособия, сообщения в блогах. До этого я 5 лет писала доки, но официально не обучалась этому. Но и неопытной меня нельзя назвать: кроме документирования API для проектов и стартапа, я ещё преподавала Python Flask на семинарах во время учёбы на последних курсах в университете. Но сейчас выпала возможность сосредоточиться только на любимом деле: помогать специалистам всех уровней через техническую документацию.

В этом году я многому научилась в сообществе Write The Docs, у других провайдеров API, а также методом проб и ошибок. В прошлом году я поделилась опытом в докладе «Что мне хотелось бы знать о написании документации» на конференции API Strategy and Practice в Портленде. Эта статья — обзор полученных знаний.

При разработке документации мы руководствуемся не только стандартами, но и удобством её использования. Стандарты определяют состав и форму документации, а формат строится исходя из удобства. Разработчик Сергей Бочаров рассказывает о пути Markdown-документа и о проблемах, которые приходится решать в обмен на простоту использования этого формата.

У меня иногда складывается впечатление, что не он служит для нас, а мы служим для этого формата. Поэтому — сэр Markdown.

Тот, кто часто заглядывает на англоязычные площадки, наверняка слышал о загадочном UX-писателе — не то копирайтере, не то проектировщике, не то чем-то среднем. Мода на эту профессию началась в прошлом году, когда сразу несколько крупных компаний, от Amazon до Paypal опубликовали соответствующие вакансии, чем вызвали бурный резонанс в сообществе. До отечественного IT сектора это поветрие не дошло, но вот отголоски дискуссий периодически доносятся и вызывают недоумение — что это все-таки за зверь? В этой статье я хочу обобщить все, что понял о сути и содержании профессии UX-писателя из штудирования зарубежных источников: зачем они нужны, что входит в круг их обязанностей и что отличает их от обычных людей (то есть дизайнеров с копирайтерами).

С чего все началось?

Интерес к проблеме отношений текста с дизайном не ослабевает уже несколько лет. Тут можно вспомнить и сакраментальное высказывание «Копирайтинг мертв» от Тони Бригнулла, и множащихся сторонников нового подхода «сначала контент» (content first), и, в качестве завершающего аккорда, недавнее выступление Джона Маэды, в котором он заявил, что «дизайнеры не понимают важность слов» и назвал писательство «навыком-единорогом». Во всем этом прослеживается одна мысль: текст играет серьезную роль не только в продвижении продукта, но и в самом продукте; это критически важная составляющая, которая требует внимания и осмысления, а не набор штампованных вспомогательных элементов.

Шесть доводов почему писатель (райтер, writer) — это турбонаддув для дизайна (от специалиста по UX в Dropbox).

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

В своем выступлении “Design in Tech 2017 " (Дизайн в технологиях 2017) Джон Маэда сказал: «Слова действительно важны, потому что графика иногда не содержит никакого смысла.» Fast Co Design продолжили эту мысль в статье под названием «Забудьте о коде: Манера письма это главный навык дизайнера».

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

Я писатель и бывший учитель английского языка и я считаю, что писать трудно. Тяжело учиться писать и тяжело этому научить. Вот почему на Амазоне более 500,000 книг о написании текстов!

Механику письма достаточно трудно постичь, но знаете ли вы, что на самом деле трудно? Такие понятия как выбор слов, тон и ритм. Чтобы овладеть этими навыками, потребуется целая вечность.

Так что же делать команде дизайнеров?

Выдуманные диалоги, реальные ситуации

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

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

Если вам интересно, каково это, быть UX-писателем, вот небольшое обзор.

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

Увертюра

Зачем это нужно?

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

Пьеса «Технический долг» в 9 частях. Ставится и показывается впервые.

Часть 0: В пустой комнате стоят Разработчик (Р) и Менеджер (М).

М: Я собрал нас тут, чтобы рассказать пренепреятнейшее известие: система КРОТОПОН, которая работает на продакшане заглючила и мы потеряли кучу денег. Кроме того нет никого, кто знает как она работает. Поэтому (с придыханием) наш СЕО дал мне священную миссию — написать новую систему. Как ты думаешь, за два месяца справишься?

Р: А что делать-то нужно?

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

Р: Эй, да это же на год работы! И вообще требования будут?

М: (В телефон) Да, конечно, за пол года справимся. (Разработчику) Ну ты тут пока начинай, а я тебе требования потом донесу.

Менеджер уходит.

Р: Но тут же…

Разработчик тяжело вздыхает, затаскивает в комнату инструменты и начинает что-то сооружать.

Введение

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

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

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

Итак — эти 7 правил:

1. Скука убивает
2. Прежде чем начать, выясните точно для себя, какие действия вы ожидаете от читателя, осилившего ваш труд
3. Пишите в соответствии с правильно сформированной структурой
4. Избегайте неоднозначных местоимений
5. Ясность = иллюстрации + слова
6. Когда имеете дело с понятиями, концепциями и т.п., используйте логическую иллюстрацию и пример
7. Не опасайтесь переделок

Работая над проектами связанными с авионикой мне потребовалось оформить несколько комплектов документации с полным описанием проекта. Также следовало учитывать требования многих ГОСТов на оформление и на содержание документации, таких как ЕСПД, КТ-178B и других.

Описание должно было в себя включать:

• Планы разработки ПО
• Требования к ПО
• Описание реализации требований к ПО
• Таблицы трассируемости(соответствия) требований к ПО и реализации
• Описание тестов на ПО (Примеры и процедуры верификации ПО)
• Таблицы трассируемости(соответствия) требований к ПО и тестов
• Отчет об обнаруженных проблемах
• Указатель конфигурации(описание версии ПО и совместимости со сторонним ПО и оборудованием)

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



Далее в статье я расскажу как я решил эту проблему.

Как вы думаете, кто лучше всего знает продукт? PM, или может быть DM? Аналитик? Интерфейс-дизайнер? Ответ на все эти вопросы, скорее всего, будет «нет». По крайней мере, в случае большого проекта. Почему?

Попробуем рассмотреть подробнее:

Главный. Он описывает концепт. Говорит: «Хочу, чтобы тут было синим, а эта кнопка всё уменьшала. А вот здесь, чтобы как в Windows 8 | iOS | в том приложении | лучше, чем у конкурента (ненужное зачеркнуть). И, очевидно, оно должно уметь делать всё красным и подкладывать квадратики».

Я веду курс веб-программирования. Когда учишь людей, поговорка «сапожник без сапог» к тебе относиться не должна: ты должен делать всё без видимых усилий и быстро. Учебник должен делаться легко и просто, и выглядеть хорошо.

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

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

В Positive Technologies технические писатели прикладывают свою руку ко всем текстам, рождающимся в недрах компании, — от сугубо технических (сопроводительная документация к продуктам, корпоративные, отраслевые стандарты) до высокохудожественных опусов с аллюзиями на Стругацких (см. легенды соревнований CTF на PHDays 2012). Если вы хотите узнать о том, как мы контролируем сроки и качество выполнения столь разноплановых задач, — добро пожаловать под кат.

Вместе с выходом второй версии фреймворка CakePHP обновилась и документация — book.cakephp.org/2.0/. А самое главное, появилась офлайновая дока. Скачать можно прям с первой страницы кукбука: CakePHPCookbook.epub. Можно скачть с гитхаба исходники или помочь с переводом и исправлением.

Мне было лень искать что-то, что читает формат .epub и я просто распаковал файлы и получил много html страничек. Такая документация выглядит примерно так. Zip с html страничками качаем отсюда

Привет, Хабр. Решил затронуть измученную во многих статьях тему, конкретнее – описать во многом нестандартное (я бы сказал, несорцовое) использование систем контроля версий (далее – СКВ). Товарищи программисты, давайте спрячем тухлые помидоры и пройдем мимо, ибо данная статья – не для вас. Да, все вы уже изучили все тонкости работы Git, SVN, CVS и знаете много других умных слов. Позвольте же и нам, простым смертным, ознакомиться со всеми преимуществами использования СКВ.
Приглашаю под кат всех желающих ознакомиться с СКВ, а также всех тех, кто, так или иначе, имеет дело с быстроменяющимися данными.

Документация – такая штука, к которой мало кто питает тёплые чувства: скучно, занудно, однообразно. И, тем не менее, иногда не возникает сомнений в её необходимости: ведь кому-то после вас этим пользоваться или, тем паче, модифицировать. И тогда появляется вопрос: как сделать документацию правильно?

Существует тьма статей на тему «как писать документацию», но если вы решили взяться за неё в первый раз, то в новой для вас области не сразу понятно, дело ли пишет автор, или отсебятину выдумывает.

Для того чтобы сформировать своё мнение без перелопачивания статей, можно пойти двумя путями: довериться некому авторитету или посмотреть в стандарты – уж там-то с наибольшей вероятностью проблему обдумали со всех сторон.

Итак, чем же может заниматься технический писатель? Традиционно технические писатели участвуют в создании:

• “онлайн-справок” для помощи в использовании программного продукта, пример такой справки — все, что появляется в любой программе по нажатию кнопки “Help”;

Итак, какими же языками пользуется технический писатель в сфере IT?

Английский. THIS IS A MUST, как говорят. Так уж сложилось, что это стандарт в мире информационных технологий. Техписатель в этой сфере просто обязан владеть им вне зависимости от того, какой у него основной рабочий язык. Иначе… увы.
Кстати, что радует, читать документацию на английском легко и приятно ( как и научные статьи, между прочим ). Пишется она обычно простым и доступным для понимания языком.
Часто даже на русском документация сложнее.

Мы все любим читать документацию. Ну, возможно, не все. Есть такие люди, которые вначале экспериментируют с каким-то прибором, доводят его до состояния “почти сломанный” и лишь потом берутся за чтение описания его работы. А некоторые даже не притронутся к нему, не прочитав все бумажки в коробке от корки до корки. Но все согласны, что документация важна и нужна. Даже для предметов, на котором только одна или две кнопки. ( а вот вы знаете, как на iPhone картинку, которая на экране, перевести на “пленку встроенной фотокамеры”? Читаем документацию. RTFM, другими словами, там все описано ).