Минимизируем документацию

О том, как минимизировать количество документации и почему это важно, рассказывает Том Джонсон. И хоть эта статья довольно старая (ей 8 лет), тренды, которые наметились в то время, подтвердились и актуальны по сей день. А значит, применимы и советы, данные в этом материале.

На одной из конференций по дизайну интерфейса докладчик Грант Скоусен показал такой рисунок:

Простота и сложность (далее…)

Ключ к написанию хорошей документации: тестирование инструкций

Всем нам попадались инструкции, в которых было или сложно найти то, что нужно, или была куча непонятных терминов, или даже отсутствовали какие-то шаги в последовательности действий. А некоторые из нас и сами писали такие инструкции ? Чтобы этого избежать, необходимо проводить тестирование документации как неотъемлемой части разрабатываемых продуктов. Статья посвящена организации тестирования документации на предприятии и проблемам, которые при этом возникают. Автор: Том Джонсон, технический писатель из США.

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

О тестировании

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

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

Итак, вам нужно документировать API…

Что такое API, для чего используется, зачем и как начать его документировать, какие инструменты использовать, как взаимодействовать с коллегами, какие существуют основные принципы. Очень полезная статья для технических писателей, которые хотят роста. Начинайте документировать API, разберитесь в этом – и карьерный рост вам обеспечен! Получить первое представление вам поможет эта статья. Автор – Лоис Паттерсон (Lois Patterson), технический писатель API из компании Global Relay (Канада).

Тяжело отследить, сколько раз API (Application Programming Interfaces, интерфейсы программирования приложений) сопровождают нашу жизнь каждый день или даже каждый час. Когда проходит ваша транзакция в PayPal или когда вас подбирает водитель Uber, само по себе API невидимо, и это более чем типично для пользовательского программного обеспечения. API используется даже тогда, когда вы встраиваете YouTube-видео в запись WordPress. При наличии сотен тысяч общедоступных API, доступных широчайшему кругу пользователей, компании находятся под большим давлением, чтобы их API были легки и удобны для использования. Не будет сюрпризом то, что рост количества вакансий, связанных с документированием API, огромен — он показывает разогретый рынок для технических писателей, которые специализируются на документировании API. (далее…)

Git, Github, управление версиями и вы

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

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

21 совет по веб-дизайну для начинающих

Мы продолжаем мини-серию статей, посвящённую дизайну, темой веб-дизайна. Здесь речь идёт не только о внешнем виде сайта, но и о текстах, удобстве и авторских правах. Кто знает, чем придётся заниматься вам, как техническому писателю, завтра? А может быть, следить за веб-сайтом компании уже входит в ваши обязанности или у вас есть свой сайт, как у небезызвестного Тома Джонсона? Тогда сегодняшний материал – для вас.

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

Что они делают для того, чтобы стать успешными?

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

Единый источник и дублированный контент (поисковая оптимизация) (Часть 2)

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

Переход от печатных к веб-моделям

Марк Бейкер расширяет задачи оглавления в комментарии к предыдущему посту. Он призывает нас перейти от печатных к веб-моделям:

Я думаю, одержимость технических коммуникаторов единым источником и повторным использованием – признак того, что они застряли в «бумажном» мышлении. Повторное использование имеет смысл в бумажном мире, потому что человек, читающий одну книгу, должен приложить массу усилий, чтобы обратиться к другой книге – в некоторых случаях это может быть несколько дней или недель усилий и значительных расходов. Лучше тогда повторять материал в каждой книге, где он может потребоваться, чем ссылаться на другую книгу, которую читателю будет трудно искать. (далее…)

Единый источник и дублированный контент (поисковая оптимизация) (Часть 1)

Если вы сумели решить проблему с написанием качественного контента, перед вами тут же встаёт новая и не менее важная: контент, к которому не могут получить доступ пользователи, ­– это впустую потраченные деньги и время. Сегодня с помощью Тома Джонсона мы попробуем понять некоторые поисковые механизмы Google и обернуть их в свою пользу.

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

Под единым источником здесь я подразумеваю несколько интернет-версий контента, не обязательно версии для различных сред. Предположим, у вас есть 9 онлайн руководств для «ACME Software»: версия 1.0, версия 2.0, версия 3.0. И для каждой версии у вас есть руководство для начинающих, руководство администратора и гайд по должностным обязанностям (для руководства). Кроме того, у вас есть печатные версии каждого из 9 руководств. Это означает, что в общей сложности их у вас 18. (далее…)

Две истории о том, как писать справку (часть 2)

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

История № 2

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

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

Как стать эффективным техническим писателем

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

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

Ниже приведены практические советы, которые помогут вам улучшить ваш стиль. (далее…)

Писательские навыки против технических, или что я понял, решая судоку (часть 2)

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

Утром я показал дочери, как решать головоломку. Стратегия поставила её в тупик.

Этот опыт заставил меня задуматься о головоломках и моём мозге. Несмотря на то, что меня всё равно никогда никто не увидит решающим судоку для собственного удовольствия, подобные испытания мне даже нравятся. Как технический писатель, каждый день я сталкиваюсь с маленькими неизвестностями, которые приходится решать. Создание алгоритма для решения конкретного вопроса — один из путей решения головоломок / решения проблем. Я обнаружил, что мой мозг замыкается на решении головоломки/кода/проблемы, и не отпускает, пока я не решу задачу.

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

Также мне нравится представлять, как части работают вместе, отдельно от кода. Я часто устраиваю безжалостное тестирование методом проб и ошибок, чтобы понять, как всё работает. Как только я разобрался, я тут же пишу описание с объяснением и перехожу к следующей проблеме. (далее…)