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

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

959 просмотров

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

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

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

Источник: vc.ru

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

Перевод статьи «Writing Good Documentation for Your Open-Source Library».

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

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

Еще одна причина того, почему разработчики осознали важность документации, состоит в конкуренции библиотек в экосистемах. До наступления эры npm эта проблема не стояла так остро. Например, в Python обычно бывает только один способ сделать что-либо. В JavaScript, до прихода Node, также не было большого числа библиотек, которые выполняли бы одну и ту же функцию разными способами. Вот попытайтесь припомнить какие-нибудь популярные альтернативы jQuery!

А сегодня мы можем выбирать себе технологический стэк. Поэтому разработчики библиотек и фреймворков прилагают значительные усилия, чтобы максимально облегчить потенциальному пользователю изучение и использование их продуктов. JavaScript-разработчики могут выбирать между Angular, React, Vue и другими, менее популярными фронтенд-фреймворками, а также между Express, Koa или Sails в бэкенде. И это еще если не считать миллионы других библиотек, занимающих промежуточное положение!

Из чего состоит хорошая документация

Документация проекта состоит из многих вещей. Например:

• Файл README
• Справочная информация
• Руководство пользователя
• Сборник рецептов
• Посты в блоге

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

README

Файл README это, зачастую, первая возможность потенциальных пользователей познакомиться с вашим продуктом. В нем могут содержаться сведения, характерные для разных типов документации (справочника, руководства и т.п.), но при этом файл README не спутаешь ни с чем другим. Этот файл помогает вам «продать» вашу open-source библиотеку. При этом не забывайте, что текст README должен быть кратким и информативным.

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

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

Наконец, включите в ваш файл README сведения о лицензии продукта и список контрибьюторов. Можно также добавить параграф о том, как принять участие в разработке вашей библиотеки. Помните, что одним из столпов open-source является уважение ко времени других людей. Если ваши потенциальные контрибьюторы смогут быстро разобраться в работе вашей библиотеки, от этого выиграют все.

Справочная информация

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

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

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

Руководство пользователя

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

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

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

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

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

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

Сборник рецептов

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

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

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

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

Посты в блоге

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

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

Учтите, что несмотря на название раздела, это может быть не пост в блоге в буквальном смысле. Вы можете сделать все вышесказанное на GitHub Gist и поместить ссылку в файл README.

Перед публикацией

Вычитка документации обязательна. Чтение документации с грамматическими и пунктуационными ошибками быстро утомляет. Обдумайте возможность дать вычитать вашу документацию носителю английского языка или кому-то, кто хорошо знает этот язык. Если этот вариант недоступен, дайте возможность вашим контрибьюторам делать пул-реквесты по документации и отдельно попросите их об этом в README. Также к вашим услугам большое количество автоматизированных инструментов, например, Grammarly или Hemingway.

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

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

Ну и, в конце концов, писать документацию не так уж и страшно!

Источник: techrocks.ru

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

14.07.2014

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

Вы руководитель проекта по разработке софта и хотите получить всю документацию к нему без лишних забот? Наши специалисты с удовольствием сделают для Вас эту работу! Подробнее на этой странице: Разработка технической документации на аутсорсинге.
Или Вы технический писатель и желаете повысить свою квалификацию? Тогда — добро пожаловать на наш курс «Разработка технических текстов и документации».

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

Метод 1 из 2: Пишем документацию для технических специалистов

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

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

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

• Если исходный код особенно длинный, его можно задокументировать в виде файла справки, который можно проиндексировать или запустить поиск по ключевым словам. Это особенно удобно для приложений, где логика программы разбита на несколько страниц и включает в себя ряд дополнительных файлов, как определённые веб-приложения.
• Некоторые языки программирования, такие как Java и .NET Framework (VisualBasic .NET, C#), имеют свои собственные стандарты для документирования кода. В этих случаях следуйте стандартам относительно того, какую часть документации нужно включить в исходный код.

1. Выберите соответствующий инструмент документирования. В какой-то степени он обусловлен языком, на котором код написан, будь то C++, C#, Visual Basic, Java или PHP, так как для этих и других языков существуют конкретные инструменты. В других случаях инструмент для использования зависит от типа необходимых документов.

• Текстовых редакторов от Microsoft Word достаточно для создания отдельных текстовых файлов документации, при условии, что документация довольно кратка и проста. Для длинных и сложных текстовых файлов многие технические писатели предпочитают специальный инструмент документирования, например Adobe FrameMaker.
• Файлы справки для документирования исходного кода можно создавать любым инструментом написания справки: RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare или HelpLogix.

Источник: protext.su