Руководство разработчика программы

Составляем документацию разработчика пошагово без диет и тренировок

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

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

• инфраструктурой as a service;

• фреймворками и библиотеками на Go, C#, TypeScript;

• трейсингом, мониторингом, логированием, нагрузочным тестированием;

• инструментами для работы с базами данных и аналитикой;

• виртуализацией и контейнеризацией.

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

Дисклеймер: в этой статье упор сделан на содержание, структуру и формат. Сугубо гуманитарные вещи вроде орфографии и пунктуации обсуждать не будем — они на вашей совести.

Зачем вам документация

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

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

• увеличивается bus-фактор: знание распространяется между большим числом людей, и его сложнее потерять;

• команда не отвлекается на ответы на одни и те же вопросы и занимается своей работой;

• коллеги быстро находят ответы (в том числе через Ctrl+F), решают проблемы и разбираются в технологии: как следствие, увеличиваются их продуктивность и доход компании;

• для внешней документации: разгружает сотрудников техподдержки.

---

Хорошая ли у вас документация?

Пройдите маленький тест и посчитайте набранные баллы:

Результаты:

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

Не торопитесь переходить к действиям — сначала налейте чай и просто прочитайте статью.

---

Шаг 1. Соберите всю информацию

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

• старая документация;

• личные страницы — ваши и коллег (например, в Confluence);

• ответы в чатах;

• репозитории (например, в GitLab);

• Word и другие текстовые редакторы;

• ссылки в закладках браузера.

На будущее: никогда не дублируйте инструкции в разных ресурсах, так их будет сложнее поддерживать: 

• легче обновить одну, чем две;

• одну из версий точно забудут обновить — и она будет вводить в заблуждение; как назло всегда будут находить именно её.

---

Шаг 2. Выбросите мусор

Одна актуальная статья лучше десяти устаревших.

Проверено: если у вас в документации найдут устаревшие сведения, никто не будет читать дальше — спросят у вас лично.

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

Под «избавлением» имеется в виду одно из двух:

• добавление в архив — предпочтительно;

• безвозвратное удаление.

Если после этого вообще ничего не осталось, это нормально.

Если вы детально не знаете начинку описываемой технологии

После такой «чистки» обычно очень легко дышится — будто камень с шеи снял.

---

Шаг 3. Найдите частые вопросы и сценарии

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

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

2. Читаете комментарии с вопросами под инструкциями, если есть.

3. Опрашиваете аудиторию. Обычно это либо пост в публичном чате, либо вопросы знакомому коллеге лично. Формы с опросами, как правило, неэффективны, поскольку собирают мало ответов.

4. Продумываете популярные сценарии с командой, ведь лучше вас продукт никто не знает.

Вначале выпишите вопросы и сценарии, а потом начинайте писать для них тексты.

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

---

Шаг 4. Поделите на разделы

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

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

Добавить их все сплошным списком вразнобой — провальный вариант. Ctrl+F тут тоже не всегда поможет, потому что, например, вы пишете в названии страницы «кубер», а ваш читатель ищет «Kubernetes» или «k8s», ничего не находит — и идёт к вам в личку.

Целевая аудитория

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

Подумайте, какие люди будут её читать. Например:

• только ваша команда;

• другие команды, им нужна одна функциональность;

• другие команды, им нужна разная функциональность;

• и ваша команда, и другие команды.

Внешние команды не должны видеть странички «Черновик to do», «[убрать в архив] 2 декабря». Держите их в отдельной папке для черновиков.

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

---

Шаг 5. Составьте словарь терминов

Одна сущность — один термин.

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

Термины должны легко находиться через Ctrl+F.

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

---

Шаг 6. Утвердите правила для команды

Заранее обговорите с командой правила и план ведения документации.

• нет структуры — статьи добавляют куда попало;

• никто не убирает устаревшую информацию;

• команда не всегда знает, что у неё есть в документации;

• много заброшенных статей;

• много пустых статей из 2016 с пометкой «to do»;

• перемешаны внутренние черновики и внешняя документация;

• нет архива;

• ведётся на русском, английском, латинском и древнегреческом.

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

Пример правил по созданию новых страниц:

Советую почитать о методике совместного ведения документации.

---

Шаг 7. Напишите тексты

Лучший способ научиться писать хорошие инструкции — это отдавать их на вычитку. Желательно — редактору. Если его нет — любому коллеге. Я не о проверке пунктуации, а о том, понятно ли написана статья, полная ли в ней информация.

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

• Освойте инструменты форматирования там, где вы ведёте документацию. Примеры: макросы Confluence, синтаксис Markdown и HTML.

  

• Укажите, для кого страница и что в ней описано, — тогда человек сразу поймёт, нужно ли ему это читать.

• Не пишите сплошные тексты — делите их на логические абзацы и разделы. При грамотной вёрстке легче сходу найти ответ.

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

• Оформите разводящую страницу. Это главная страница с основной информацией и разделами по темам. Она нужна, чтобы читатель быстро понял, где искать необходимую инструкцию.
  Пример Ozon Docs
  Пример Yandex Cloud
  Пример Amazon EC2

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

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

• Избегайте канцеляризмов — они утяжеляют тексты: «для того чтобы в данном процессе осуществить определённую функциональность».

• Выделяйте в тексте важное, но не превращайте его в одни сплошные плашки.

• Укажите контакты команды, чтобы читатели знали, к кому обращаться.

---

Шаг 8. Добавьте FAQ

FAQ — страница с часто задаваемыми вопросами и ответами на них. 

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

Используйте список из шага 3, если он есть.

FAQ — это не полноценная инструкция. Не дублируйте тексты и не делайте ответы очень подробными. 

Оптимальный вариант — краткий ответ со ссылкой на полную инструкцию. Например, «Да, это возможно. Подробнее в статье “Как создать N”».

Для продвинутых идеалистов:

Вопросы можно сгруппировать по темам — так их будет проще найти. Такие страницы FAQ обычно очень нравятся разработчикам, но это не принципиально, потому что обычно вопросы ищут с помощью Ctrl+F.

---

Шаг 9. Продумайте, как вашу документацию будут находить

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

Подумайте, куда ваши коллеги чаще обращаются за помощью:

• к вам в личку: закрепите ссылку на документацию у себя в профиле на корпоративном портале;

• в ваш чат: закрепите ссылку в шапке, закреплённом сообщении, сделайте так, чтобы каждому вступившему ссылку отправлял бот;

• в поиск Confluence: удалите устаревшую информацию, если ещё этого не сделали, чтобы она не всплывала, понятно называйте статьи.

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

---

Шаг 10. Проанализируйте результат

Лучший источник для анализа — ваша аудитория. 

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

Что обычно делаю я:

• Считаю количество запросов в чатах. 

• Провожу мини-исследование среди читателей: готовлю открытые вопросы, спрашиваю, долго ли они искали информацию, что именно они искали, нашли ли ответы на свои вопросы.

• Изучаю статистику просмотров в Confluence и Grafana: если за месяц никто не обратился к документации, нужна ли она?

Сама не практикую, но отличная идея:

• Добавить фичу «Оцените статью». Такие макросы точно есть в Confluence.

Если на этом этапе не всё гладко — это нормально, просто будьте готовы что-то дописать, поменять местонахождение статьи.

---

Итог

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

И помните, что документация — ваш общий продукт. 

Буду рада ответить на ваши вопросы. Делитесь мнением и историями в комментариях.

Назначение

Программа “Руководство разработчика” – это редактируемый справочник, содержащий информацию о среде разработки “My Visual Database“, а также реестр пользовательских проектов, созданных на данной платформе.

Скриншоты

Описание

Ключевые особенности

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

Операции, которые реализованы в программе:

• Синхронизация папок проектов: добавление проектов, анализ модульной структуры, формирование списка процедур и функций
• Визуализация отдельных программных частей проекта: модулей и процедур/функций с подсветкой синтаксиса
• Чистка проектов (удаление ненужных файлов)
• Форматирование исходных кодов проекта в стандарте Delphi
• Открытие проекта в среде разработки
• Комплексный поиск по ключевым словам
• Ведение базы сниппетов (кусочки кода для решения конкретной задачи)

Скачать

• Руководство разработчика 1.8, project.rar – архив с программой и файлами проекта

Стоимость лицензии

Программа бесплатная, распространяется без ограничений.

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

Назначение руководства программиста

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

Примерами могут служить:

– библиотека функций;

– платформа или среда для разработки ПО;

– ПО с открытым кодом.

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

– назначение, структуру входных и выходных данных программных функций;

– возможности по созданию программного кода, особенности его интерпретации и компиляции;

– синтаксические особенности используемого языка программирования;

– возможные правила и ограничения при работе с программным кодом;

– различные инструкции по работе с программой.

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

Состав типового руководства программиста

В соответствии с требованиями ГОСТ руководство программиста должно содержать следующие разделы:

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

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

– Обращение к программе, где указывают способы и параметры запуска программы;

– Входные и выходные данные, где описывают формат, способ организации и другие требования к входным и выходным данным;

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

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

Стандарты для руководства программиста

ГОСТы регламентируют и этот документ, в данном случае это ГОСТ 19.504. В соответствии с ним определяется структура и содержание Руководства программиста.

Заключение

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

---

– разработка руководства администратора;
– создание руководства пользователя;
– разработка руководства оператора.

---

УФИМСКИЙ ГОСУДАРСТВЕННЫЙ
АВИАЦИОННЫЙ ТЕХНИЧЕСКИЙ УНИВЕРСИТЕТ

КАФЕДРА ВЫЧИСЛИТЕЛЬНОЙ
МАТЕМАТИКИ И КИБЕРНЕТИКИ

Прикладное
программное обеспечение для учета
заявок и контроля их исполнения на
примере ООО «Интегрированная транспортная
сеть».

1. Руководство программиста

Листов
14

УФА
2013

1. Аннотация

Приводится
руководство программиста программного
обеспечения для учета заявок и контроля
их исполнения на примере ООО «Интегрированная
транспортная сеть».

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

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

1. Назначение программы

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

1. 2. Условия, необходимые для выполнения программы

Для
работы программного продукта необходима
следующая программно-аппаратная
конфигурация:

• Windows
  7,Windows Server 2003 Service Pack 2,Windows Server 2008,Windows
  Server 2008 R2,Windows Vista, Windows Vista Service Pack 1,Windows
  XP Service Pack 2,Windows XP Service Pack 3;

• 32-разрядные
  системы: компьютер, оборудованный
  процессором Intel
  или совместимым процессором с тактовой
  частотой 1 ГГц или выше (рекомендуется
  2 ГГц или выше, поддерживается только
  один процессор);

• 64-разрядные
  системы: процессор с тактовой частотой
  1,4 ГГц или выше (рекомендуется 2 ГГц или
  выше, поддерживается только один
  процессор);

• минимальный
  объем ОЗУ 512 МБ (рекомендуется 1 ГБ или
  более);

• 1
  ГБ свободного места на диске;

• наличие
  СУБД:
  MS SQL 2008;

1. 3. Характеристики программы

2. 3.1.
   Режим работы программы

Диалоговый.
Web-интерфейс
в браузере (с поддержкой HTML5).

1. 3.2.Средства
   проверки правильности выполнения
   программы

Проверка
правильности работы программы
осуществляется при выполнении конкретных
примеров. Программа
выдает сообщение при вводе некорректных
данных (Рис. 2.20):

Рис. 2.20.
Некорректный ввод номера телефона

1. 3.3.
   Функционирование программы после сбоев

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

1. Обращение
   к программе

Для
запуска программы необходимо выполнить
следующие действия:

• Запустить
  программу на ПК, с поддержкой Microsoft
  .NET
  Framework
  (или на удаленном сервере), если он еще
  не запущен;

• Откройте
  ваш любимый браузер (на пример chrome,
  internet
  explorer,
  mozilla
  firefox);

• Введите
  в адресную строку IP-адрес
  сервера, с заранее определенным портом;

• Откроется
  страница домашняя страница;

• Начать
  работу
  с клиентами.

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

Соседние файлы в предмете [НЕСОРТИРОВАННОЕ]

• #
• #
• #
• #
• #
• #
• #
• #
• #
• #
• #

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

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

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

Часто подобную документацию пишут в текстовых редакторах, но это значительно усложняет и без того скучный процесс. Специализированное ПО имеет множество функций, упрощающих процесс создания руководства. Например, возможность структурировать будущую документацию, создавать разделы, делать пояснения на скриншотах, экспортировать контент в различные форматы (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 можно работать в команде. Сервис позволяет следить за процессом разработки, оставлять комментарии, от которых уведомления будут приходить на почту, раздавать роли.

Плюсы:

+ Возможность работы в команде через веб-интерфейс и отслеживание результатов.

+ Поиск по документации.

+ Автоматический перевод документации на любые языки.

Минусы:

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

— Высокая стоимость лицензии.

— Нет возможности работать в offline-режиме.

4. HelpSmith

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

Цена – от $199.

Одной из основных возможностей HelpSmith является создание нескольких форматов справки из единого источника. Таким образом, имея один исходный текст, вы можете экспортировать его в HTML для создания веб-справки, в PDF, MS Word, а также в формат ePub для электронных книг.

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

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

Следует отметить, что файл справки или систему веб-справки можно легко интегрировать в ваше приложение или веб-сайт, поэтому вы можете предоставлять контекстно-зависимую справку, экспортируя список тем в файл заголовка, совместимый с вашей IDE, такой как C #, VB .NET, Delphi, C++, MS Office VBA.

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

Плюсы:

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

+ простота и удобства использования.

Минусы:

— Отсутствие простого механизма многопользовательской работы

— Интерфейс и материалы на английском языке

— Отсутствие Mac и веб-версии

5. MarkdownPad

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

Цена – бесплатно. Есть платная версия – $15.

MarkdownPad — известный редактор Markdown для Windows. Он прост и так же удобен в использовании, как Microsoft Word, и поставляется с редактором WYSIWYG, поэтому вам даже не нужно знать Markdown.

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

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

Плюсы:

+ Очень удобная и в целом простая программа, что даже не получилось написать про неё больше 3 абзацев

+ Стоимость.

Минусы:

— Малый функционал, по сравнению с большинством подобных инструментов.

Заключение

Пользовательская документация – незаменимый инструмент, позволяющий укреплять лояльность пользователей, прикрывать техподдержку, повышать SEO-факторы продукта. Кроме того, наличие технической документации — один из основных критериев допуска в Реестр отечественного ПО Минцифра России.

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