Edit me

Первоначально материал собирался автором, чтобы провести серию семинаров для фирмы, пишущей о технологиях, в районе San Francisco Bay area. Они чувствовали, что должны либо обучить своих существующих технических писателей тому, как документировать API, либо сократить некоторых своих писателей. Автор преподавал серию из трех семинаров, проводимых по вечерам, которые длились несколько недель.

Эти семинары были динамичными и познакомили работников со множеством новых инструментов, технологий и рабочих процессов. Даже для писателей, которые работали в области технических коммуникаций в течение 20 лет, документация API представляла проблемы и вызовы. Технологическая среда настолько обширна, что даже у писателей, которые хорошо знакомы с одной технологией, технический опыт не всегда сопоставим с документированием REST API.

После семинаров автор разместил материал на сайте idratherbewriting.com и открыл его для более широкого круга технических писателей. Сделал это по нескольким причинам:

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

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

Tom, this course is great. I’m only part way through it, but it already helped me get a job by appearing fluent in APIs during an interview. Thanks for doing this. I can’t imagine how many volunteer hours you’ve put into helping the technical communication community here.

Другой комментарий:

Hi Tom, I went through the whole course. Its highly valuable and I learned a bunch of things that I am already applying to real world documentation projects. … I think for sure the most valuable thing about your course is the clear step by step procedural stuff that gives the reader hands-on examples to follow (its so great to follow a course by an actual tech. writer!)

И еще один:

I love this course (I may have already posted that)—it’s the best resource I have come across, explained in terms I understand. I’ve used it as a basis for my style guide and my API documentation….

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

Just an email to thank you for the wonderful API course on your site. I am a long-time tech writer for online help that was recently assigned a task to document a public API. I had no experience in the subject, but had to complete a plan within a single sprint. Luckily I remembered from your blog posts over the years that you had posted material about this. Your course on YouTube gave me enough information and understanding to be able to speak intelligently on the subject with developers in a short timeframe, and to dive into tools and publishing solutions.

И такой:

I am nearly in tears after finding this site! I think I stumbled upon it some time ago, but I must not have been ready for what you have to say. NOW I am ready! As a former technical writer now knowledge manager, I stumbled upon API writing and have learned a lot simply by being curious and observant…

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

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

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

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

🔙

Go next ➡