Публикации
Адвокат пользователя: пересечение воображаемого разлома
23.09.2016
Фил Девис (Phil Davis) занимается управлением разработки документации в Integral Development Corp. в Калифорнии. За 20 лет работы он много раз сталкивался с мифами о работе технических писателей и в сегодняшней статье развенчивает один из них. Итак, могут ли программисты писать, а писатели программировать?
В последнее время я часто слышу много сплетен о мифе: писатели не могут программировать, а программисты не могут писать.
Большинство этих сплетен идут от несостоявшихся писателей и писателей-философов, которые заявляют, что этот миф — полнейшая ерунда.
Согласен, но также я начал задавать себе вопросы: Почему этот миф существует? Почему мы обсуждаем его сейчас? Что он значит? Читать дальше…
Итак, вам нужно документировать API…
09.09.2016
Что такое API, для чего используется, зачем и как начать его документировать, какие инструменты использовать, как взаимодействовать с коллегами, какие существуют основные принципы. Очень полезная статья для технических писателей, которые хотят роста. Начинайте документировать API, разберитесь в этом – и карьерный рост вам обеспечен! Получить первое представление вам поможет эта статья. Автор – Лоис Паттерсон (Lois Patterson), технический писатель API из компании Global Relay (Канада).
Тяжело отследить, сколько раз API (Application Programming Interfaces, интерфейсы программирования приложений) сопровождают нашу жизнь каждый день или даже каждый час. Когда проходит ваша транзакция в PayPal или когда вас подбирает водитель Uber, само по себе API невидимо, и это более чем типично для пользовательского программного обеспечения. API используется даже тогда, когда вы встраиваете YouTube-видео в запись WordPress. При наличии сотен тысяч общедоступных API, доступных широчайшему кругу пользователей, компании находятся под большим давлением, чтобы их API были легки и удобны для использования. Не будет сюрпризом то, что рост количества вакансий, связанных с документированием API, огромен — он показывает разогретый рынок для технических писателей, которые специализируются на документировании API. Читать дальше…
Читерские коды для хорошей документации (часть 2)
26.06.2014
Мы продолжаем статью разработчика-идеолога Брендона Уэста о важности грамотного подхода к созданию документации. Возможно, она вдохновит кого-то на глобальные перемены в компании.
Большое количество документации – проблема разработчиков
Давайте ещё раз рассмотрим эти категории. «Описательная» категория должна в основном заполняться маркетинговой командой. Таким документам не обязательно быть сильно техническими, но они должны направлять людей к более техническим разделам документации, которая может быть востребована аудиторией. Технический справочник и код требуют участия разработчиков, которые будут либо передавать писателю технические детали, либо лично писать образцы кода. Учебные материалы требуют, чтобы разработчики формулировали и создавали решения. А интерактивные системы требуют от технической группы ресурсы для реализации (и, возможно, поддержки).
Три из четырёх категорий требуют участия разработчиков, и мы обнаружили, что это работает не только в теории, но и на практике: в хранилище документов компании SendGrid около 230 HTML-страниц, но больше 2100 блоков кода. Эти коды писали кодеры, а не писатели. Если ваши разработчики будут заинтересованы в документации, то они будут заинтересованы и в её создании с точки зрения её содержания. И конечно, если вы захотите настроить под себя платформу, на которой создано хранилище документации, вам нужен разработчик. Читать дальше…
Читерские коды для хорошей документации (часть 1)
25.06.2014
Брендон Уэст – разработчик-идеолог в компании SendGrid – необычный человек. Согласитесь, не часто встретишь разработчика, который заботится о качестве документации, да ещё и пропагандирует такой подход среди коллег. Сегодня мы познакомимся с его статьёй о важности качественной документации.
Все, особенно разработчики, обожают работу над документацией. Они понимают важность документов и их влияние на принятие покупателем продукта и опыт клиента. Они всегда учитывают документацию при планировании и выпуске кода. Постойте, над чем это вы смеётесь?
У многих компаний есть проблемы с документацией. Из-за огромного количества типичных проблем сложно отстоять документацию; информация устаревает, ей не хватает полноты, контент плохо организован и противоречив, читатели не могут найти то, что ищут, а образцы кода могут быть неверными. Если вы зайдёте в отдел разработки и попросите добровольцев для обновления документации, вас встретят тишиной, если не откровенной насмешкой.
Правда в том, что нет читерских кодов, чтобы создать культуру, где ценят документацию, или чтобы создавать качественный контент, но я хочу поделиться практическими уловками, которым я научился, пытаясь создавать такую культуру для сервиса SendGrid. Надеюсь, я подарю вам пару дополнительных жизней (ну или хотя бы дополнительное здоровье) в этой игре. Читать дальше…
Как стать техническим писателем API
20.06.2014
Мы решили не обойти вниманием в нашем блоге ещё один актуальный вопрос технического писательства – документацию для API. Уже любимая нами Сара Мэддокс, технический писатель API компании Google, снова готова поделиться опытом.
Один мой знакомый технический писатель недавно спросил, если ли у меня советы, как стать техническим писателем API. Это человек, который пишет документацию, ориентированную на разработчика и описывающую программный интерфейс приложения (API), набор средств для разработчиков программного обеспечения (SDK) и другие инструменты, которые разработчики используют, чтобы заставить одно приложение «общаться» с другим. Я могу поделиться некоторыми советами.
В ориентированной на разработчика документации есть три стороны – написание, технологии и «отношение». Читать дальше…
Итоги конференции Гипербатон
27.05.2014
24 мая 2014 года в Москве прошла конференция Гипербатон, проводимая компанией Яндекс. На конференцию съехались специалисты по документированию и техническому переводу из разных уголков России и ближнего зарубежья. В течение субботнего дня прозвучали 7 тематических докладов, так или иначе связанных с тематиками технического писательства, локализации программных продуктов и документации, а также технического перевода. В работе конференции, кроме докладчиков от компании Яндекс приняли участие представители компаний Лаборатория Касперского, ABBYY и ПроТекст.
Открыла конференцию Светлана Каюшина, руководитель службы разработки технической документации компании Яндекс. Светлана пояснила выбор названия конференции, которая проводилась впервые, рассказала о предпосылках организации конференции. Также Светлана предложила присоединиться к сообществу технических писателей, организованному компанией Яндекс.
Продолжил конференцию Кирилл Маслинский, ведущий разработчик технической документации компании Яндекс с докладом о профессии технического писателя. Кирилл рассказал об истории этой профессии, профессиональной идентичности технических писателей, а также привёл интересную статистику о людях, которые приходят в профессию технических писателей и качествах, которыми они должны обладать.
Арина Кирпичева, разработчик технической документации компании Яндекс, рассказала о первых 5 месяцах своей работы в компании. Её работа связана с документированием API сервиса Яндекс.Карты. Арина рассказала о том, с какими проблемами ей пришлось столкнуться в начале работы и как они были преодолены. Она внушила слушателям мысль о том, что какая бы сложная задача перед писателем не стояла, её всегда можно решить, разбив сложную задачу на этапы и не пренебрегая горизонтальными связями в компании, в которой работаешь. Читать дальше…
Технический писатель Google. 3 месяца в компании (часть 3)
17.01.2014
Мы заканчиваем публикацию статьи технического писателя Google Сары Мэддокс. Сегодня мы узнаем, какие инструменты используют работники компании, какими навыками должны обладать и какие преимущества можно получить, устроившись работать в Google.
Слова, код, разметка
Нужно ли уметь писать код, чтобы быть техническим писателем в Google? Это наиболее обсуждаемый вопрос. Я думаю, всё зависит от должности, занимаемой в Google. Для моей позиции, я бы сказала, было бы весьма невыгодно не уметь скомпоновать программный код.
Почти все, что мы создаем – это слова. Мы пишем в HTML или Markdown в зависимости от нашего выбора, либо существующего формата, если мы обновляем документ.
Технический писатель Google. 3 месяца в компании (часть 1)
13.01.2014
Представляем статью Сары Мэддокс, которая несколько месяцев назад получила место технического писателя в корпорации Google и теперь делится впечатлениями с читателями своего блога.
Многие спрашивают меня, каково же быть техническим писателем в Google. Я стала частью команды Google три месяца назад. Теперь, как красноречиво заметил мой руководитель, «блеск первых впечатлений от работы стирается», и я принимаюсь за будничную работу. Итак, каково это?
Тяжело ответить на этот вопрос. Это бодряще, страшно, весело, разочаровывающе, вдохновляюще, утомительно. Всё, чего можно ожидать от новой работы, и ещё многое. Мне это нравится. Чаще всего 😉
Чтобы ответить на вопрос, я начала записывать какие-то случайные мысли, а потом описала «день из жизни». Надеюсь, это даст вам некоторое представление о том, что я здесь творю.
Записи докладов конференции ТехДок 2013
28.11.2013
27 и 28 ноября прошла конференция ТехДок 2013. Ура! 🙂
Спасибо всем докладчикам, участникам, а также информационным партнёрам, которые помогли нам собрать аудиторию. Максимальное одновременное количество участников онлайн было 118 человек, и цифра не опускалась весь день ниже 100. Мы очень рады, что мероприятие вызвало интерес и собрало множество положительных откликов! Теперь конференция для технических писателей станет ежегодным событием, и мы будем рады, если аудитория будет расширяться, и в России и странах ближнего зарубежья появится сообщество технических писателей, редакторов и переводчиков. Вместе веселее! 🙂
С удовольствием принимаем отзывы на электронную почту (info@protext.su), в соцетях и на сайте. Уже есть дельные замечания и мы постараемся учесть их в будущем.
Представляем записи докладов конференции. Читать дальше…