В чем писать техническую документацию

Где писать пользовательскую документацию к ПО: лучшие программы и сервисы

Многие согласятся, что написание документации пользователя к ПО или сервису нелегкая задача.

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

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

Часто подобную документацию пишут в текстовых редакторах, но это значительно усложняет и без того скучный процесс. Специализированное ПО имеет множество функций, упрощающих процесс создания руководства. Например, возможность структурировать будущую документацию, создавать разделы, делать пояснения на скриншотах, экспортировать контент в различные форматы (HTML, CHM, PDF) и многое другое.

Если вам не нравится процесс документирования продукта, над которым вы работаете, этот обзор для вас.

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

Но разве техническая поддержка не может стать заменой документации?

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

— Поддержка может подвести. Случайно или из-за некомпетентности сотрудников. Грубость техподдержки – тоже нередкое явление.

Также, техподдержку могут просто завалить вопросами, и она не будет успевать отвечать.

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

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

1. Dr.Explain

Операционная система – Windows

Цена – от 10 000 рублей в год или 16000 рублей навсегда в рамках старшей версии (есть бесплатная версия)

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

Второе, что бросается в глаза, когда изучаешь возможности программы — встроенные шаблоны документации. Всегда проще работать по образцу, смотреть на пример документации, дополнять и видоизменять под свой продукт. Именно это и предлагает Dr.Explain. В программе существует три шаблона документации: руководство пользователя для ПО, руководство пользователя для web-сервиса и шаблон корпоративной базы знаний.

Как бы хорошо программа не помогала писать документацию, конечная цель – это публикация контента на сайте продукта и интеграция его в продукт, чтобы пользователи могли прочитать ваше руководство. Dr.Explain позволяет экспортировать ваш проект в популярные форматы: HTML – для сайта, CHM – для встроенной в ПО справки и PDF.

Dr.Explain позволяет работать в команде через облачный сервис или локальный сервер. В программе можно задавать разделам «степень готовности». Так вы сможете контролировать процесс написания справки.

В программе имеется удобный и продуманный WYSIWYG (What You See Is What You Get, «что видишь, то и получишь») редактор, возможность настраивать стиль вашей документации, возможность настроить контекстно-зависимую справку и что немаловажно – в ней есть русский интерфейс, так как Dr.Explain – проект отечественной команды разработчиков и продукт включен в реестр отечественного ПО.

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

+ Простая оплата для российских пользователей

— Отсутствие версии для Mac и Linux

— Нет вывода в ePub, markdown и другие специфические форматы

2. HelpnDoc

Операционная система – Windows

Цена – от $99 в год (есть бесплатная версия)

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

Создаёте документацию для мобильного приложения? Вашим пользователям нужно читать документацию с электронной книги? Нужно создать документацию к продукту на Linux, Ubutu, UNIX? Эта программа поможет.

Мощная система медиабиблиотеки. Все медиа-элементы, такие как изображения, видео, документы, фрагменты HTML-кода, управляются библиотекой: эти медиа-элементы можно использовать повторно много раз.

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

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

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

+ Возможность создания мультиформатной документации.

+ «Сценарии» значительно упрощают и ускоряют процесс написания руководства

+ Умный анализ и проверка вашего проекта.

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

— сравнительно сложный пользовательский интерфейс.

— сложность с оплатой лицензий для российских пользователей.

3. ClickHelp

Операционная система – любая.

Цена – от $50 в месяц.

ClickHelp в отличие от двух предыдущих – не программа, это web-сервис для создания документации.

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

Представьте, что пользователи открывают руководство и пытаются найти что-то по определенной теме. Вводят в поиск термин и им выдается все множество совпадений, которые только есть.

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

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

— Система индексов. Если вы думаете, что пользователю все равно будет трудно найти какую-то информацию в вашей документации – система индексов или таксономий в ClickHelp решит эту проблему. Данная функция предназначена для того, чтобы сделать темы доступными для поиска по терминам, которые не находятся непосредственно в их содержании. Например, если в документации есть тема о SSL-шифровании, вы можете присвоить ей индексное ключевое слово «безопасность», и даже если в теме нет ни единого упоминания «безопасности» или каких-либо производных, она все равно будет доступны для поиска по этому термину.

В ClickHelp можно работать в команде. Сервис позволяет следить за процессом разработки, оставлять комментарии, от которых уведомления будут приходить на почту, раздавать роли.

Как написать идеальную техническую документацию

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

И если в ТД будет всего одна ошибка, пользователь начнёт проверять каждую реплику — особенно при описании API и архитектуры. В итоге документ потеряет эффективность.

Чтобы такого не случилось ни в документации к играм, ни к корпоративным ПО стоит пройти несколько шагов.

Проведите исследование

Анализ — это стартовая точка в создании любой технической документации. Он начинается с изучения:

Цели. Подумайте, чем документ будет полезен пользователям.
Текущей технической документации. Уточните актуальность имеющихся данных. Если большая часть устарела, документ лучше писать с нуля.
Аудитории. Определите, кто ваш читатель — члены команды, эксперты, широкая публика и т. д. Например, рядовых пользователей отпугнёт обилие терминов, а IT-специалистов напряжёт блок для новичков.
Документации в других сервисах. Посмотрите на Stripe, Exolve, 2ГИС, Superjob и так далее. Референсы всегда помогают понять, как это можно реализовать на практике.

Например, мануал ниже рассчитан на массового читателя — в нём нет сложных формулировок, зато достаточно много подробных скриншотов.

А здесь у Nexweave уклон идёт на шаблоны кода, поскольку документация по API в основном пишется под IT-группу.

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

Планируйте техническую документацию

Каждая ТД уникальна и составляется с учётом целей компании и интересов аудитории. Но даже в этом случае «скелет» документации часто включает в себя такие элементы:

Название. Описывает, о чём пойдёт речь в материале.
Оглавление. Показывает имеющиеся темы и даёт возможность сразу перейти к нужной.
Версия и дата последнего обновления. Демонстрирует актуальность данных (больше для внутреннего пользования).
Описание ЦА. Обозначает, кому будет полезен документ в первую очередь.
Разделы и подразделы. Содержат основную информацию, ради которой и создавалась техническая документация.
Ссылки и другие дополнительные ресурсы. Переводят на смежные разделы, статьи блога и прочие источники с информацией о понятиях или процессах, описанных в ТД.

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

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

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

При этом кроме общей структуры ТД желательно планировать содержание каждой её страницы. Вот как это сделали в Stripe:

Как создавать и оформлять техническую документацию в IT: рекомендации для начинающих и подсказки для опытных

Меня зовут Ирина Исай, я техрайтерка киберспортивного медиахолдинга WePlay Esports, части холдинга TECHIIA. В предыдущей статье я рассказывала об аудите технической документации , подходах и лучших практиках. После материала я получила много вопросов от коллег по цеху и тех, кто думает перейти в техрайтинг, как писать и структурировать документацию.

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

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

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

«Да что там — просто сесть и написать»

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

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

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

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

Далее посмотрите имеющуюся техническую документацию: юзер-кейсы, технические требования и тому подобное. Мне нравится ходить по доскам Jira продуктовых команд и там собирать информацию. Все собираем, структурируем (можно даже в табличку для удобства). Но даже на этом этапе, когда кажется, что появилось какое-то понимание продукта, писать мануал рано.

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

Например, ISO рекомендует создать профили своих читателей:

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

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

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

Чего я не делаю: уровни, правила, обещания

Не делаю документацию слишком глубокой по уровням. Из своего опыта и по советам коллег знаю, что если вы не Boeing, где каждая статья может иметь подстатьи, вспомогательные или смежные статьи, то ваш максимум — 3-4 уровня документации. Если больше — мануал-гайды-статьи-подстатьи — никто так глубоко не будет читать, потому что будет сложно найти нужную информацию.

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

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

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

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

В конце каждой статьи я еще даю ссылки на смежные материалы — дополнительный или смежный функционал. Никогда не делаю ссылок в середине текста: в PDF не всё кликается, в Confluence ссылки могут ломаться, когда нужно мигрировать на другой райтерский инструмент. Как правило, создаю раздел Read more в конце гайда и добавляю списком несколько ссылок.

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

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

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

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

Совет. Заголовки — мое любимое. Иногда наталкиваюсь на такой заголовок-аббревиатуру, что и не догадаешься, о чем речь. Иногда наоборот — две-три строки текста в заголовке — пока дочитал, забыл, зачем зашел.

У меня есть правило, что заголовок должен поместиться в одну строку, а еще лучше — в половину строки. Всегда нужно помнить, что ваш читатель может пользоваться устройствами с различным размером экрана, а текст может иметь различные форматы: PDF, HTML и тому подобное. Отсюда проблема с длиной строки и возможностью его дочитать. Его может «съесть» поле экрана, а вам нужно не раздражать читателя, а дать ему возможность увидеть весь текст сразу.

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

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

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

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

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

Рабочие моменты

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

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

Еще веселее, когда такая кнопка или любой другой элемент просто есть, но не работает. Можно обратиться к команде, чтобы как-то их скрыть, выпилить, но это не всегда возможно, не всегда есть ресурс. В таком случае я игнорирую элемент, не описываю. Хотя остается риск, что пользователь найдет этот нюанс и начнет расспрашивать — тогда будет немного неловко. Как правило, пользователь интересуется в документации тем, что нужно решить именно ему, и не замечает таких «недостатков». Задача техрайтера — предоставить пользователю полезную информацию.

Я так спокойно об этом говорю, потому что продукт — живой организм, он постоянно меняется.

Иногда, например, встречаются сюрпризы с наименованием элементов продукта. Работают себе две команды параллельно, или одна пришла сразу после другой. Они что-то создали, и каждый назвал «что-то» по своему усмотрению. Например, одну и ту же кнопку одни подписали Add, а другие — Create. Вроде и небольшая проблема. Но, во-первых, я за консистентность, а во-вторых, между этими двумя глаголами большая разница. В таком случае я предлагаю командам договориться и остановиться на одном названии, добавляю им объяснения со ссылками на словари, в чем же разница.

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

лучшие практики для написания технической документации

Пример рекомендации о разнице слов

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

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

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

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

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

Совет. Если у вас много команд и много продуктов, можно попробовать применить принцип CI / CD (continuous integration / continuous development). Возможно, даже к работе с документацией, которую создали до вас.

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

документация к продукту

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

Выбор инструмента для написания документации. Здесь речь пойдет именно о райтерских инструментах.

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

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

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

MadCap Flare для написания документации

Скрин программы MadCap Flare

И вот счастливая я переношу всю документацию в MadCap Flare. Здесь мы делаем следующее:

пишем абсолютно все статьи — их мы тоже публикуем в Confluence для продуктовых команд, а еще это некий «бэкап» информации;
централизованно создаем стиль и форматируем тексты (обычно это форматы PDF, HTML5)
ведем свой глоссарий с определениями;
обязательно поддерживаем «переменные» — как правило, это имена, которые мы вводим с помощью глоссария. Их можно удобно из одного источника заменить во всех мануалах, если вдруг возникнет необходимость;
обязательно для работы в таком инструменте есть специальный гайд, который определяет все критические вопросы: стиль, грамматика, работа с визуализацией и тому подобное.

Маленький тест на определение техрайтера

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

Хороший техрайтер — тот, кто обращает внимание на детали и ищет возможность задокументировать должным образом что угодно. Например, как сделать скриншот со Smart TV без специального устройства? Хорошо, если вы работаете в Samsung и в ваших руках есть множество инструментов. А тем, кто подумал о фото экрана телевизора, сделанное на телефон, пока отказано в доступе в мир инструкций, гайдов и мануалов.

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

Добавлю здесь свои любимые READ MORE. Список можно продолжить — эти ссылки только для вдохновения:

The Chicago Manual of Style ;
Microsoft Style Guide ;
AWS Documentation ;
I’d rather be writing ;
Medium .

Оригинал статьи на dou.ua .

Как писать документацию к программному обеспечению

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

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

Существуют два способа написания технической документации.

Способ 1. Написание технической документации для специалистов.

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

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

3. Инструмент для документирования. Определяется языком, на котором создается данный программный продукт и типом требуемых документов.

Способ 2. Написание технической документации для конечных пользователей.

1. Основание для документации. Документальное сопровождение необходимо для любого программного продукта, чтобы показать пользователям пути его применения и оказать техническое сопровождение. Также в таких документах указываются правовые условия.

2. Определение целевой аудитории. Достаточно редко широкий круг пользователей является специалистами в какой-то конкретной области. Для выделения целевой аудитории:

— определите круг должностей сотрудников, которые будут работать с программным приложением,

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

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

3. Выберите формат подачи данных при написании технической документации. Обычно это или справочное руководство, или руководство пользователя.

4. Выберите форму для документов (различные справки, PDF-файлы, печатные руководства и т.д.).

5. Выберите удобный инструмент документирования (программное обеспечение).