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

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

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

Журавлев Денис

Что такое руководство пользователя и для чего его создавать

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

Каждый программный продукт нуждается в руководстве пользователя

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

Общие советы по созданию пользовательской документации

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

После этого важно подумать о том:

  • Где пользователь будет к нему обращаться: дома, на работе, в машине?
  • Как часто он будет его просматривать?
  • Насколько объективно сложен для понимания продукт?

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

Определившись со всеми представленными пунктами, станет понятнее, какой нужно использовать стиль изложения, какого объема написать текст. Но помните, что излишне стилистически окрашенные слова мешают пользователю добраться до сути. Так что лучшим вариантом в большинстве случаев будет нейтрально-формальный стиль. Пишите так, чтобы пользователь вас понял. Постарайтесь по возможности избегать технических терминов, но проанализируйте – не сделает ли полное отсутствие терминов ваше руководство бесполезным?

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

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

В первом разделе желательно рассказать общую информацию о программе:

  • Для чего создан продукт.
  • Какие задачи он решает.
  • Какие основные выгоды от использования для клиента.

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

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

Ни одно руководство не обойдется без таких разделов как: “Частые вопросы” и “Устранение типовых проблем” В них разбираются вопросы и проблемы, с которыми часто сталкиваются пользователи. Для заполнения данного раздела вам скорее всего понадобятся уже готовые отзывы клиентов. Если у вас абсолютно новый продукт, вы можете предугадать проблемы ваших клиентов либо на первое время не включать данный пункт в ваше руководство.  

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

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

Но как создать руководство пользователя, если пишешь его впервые? Или что делать, если руководство пользователя нужно постоянно обновлять и дорабатывать? Или нужны особые функции, которых нет в традиционных текстовых редакторах, например, в MS Word.

Одним из популярных инструментов для создания качественного руководства является программа Dr. Explain (https://www.drexplain.ru), в которой уже есть готовые шаблоны руководств пользователя с готовой структурой разделов и в которой удобно обновлять документацию, как бы часто эти обновления не происходили.

Видео-обзор основных возможностей программы Dr.Explain

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

Любой проект в Dr.Explain вы можете создать с нуля или импортировать уже существующую документацию, например из формата MS Word, HTML или CHM-файла, и буквально за несколько минут создать из нее онлайн-помощь, файл справки в формате CHM, или документ в формате PDF.  

Экспорт руководства пользователя в различные форматы

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

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

У программы свой собственный редактор, оптимизированный под работу со сложной документацией. Основные функции редактора вынесены в компактный тулбар. Это – управление стилем текста, форматирование абзацев, вставка ссылок, изображений, видео, таблиц и списков, а также вставка специальных объектов. Dr. Explain экономит время и силы своих пользователей. Разработчики документации часто сталкиваются с проблемой многократного использования одного и того же фрагмента текста и прибегают к очевидным решениям – “Ctrl+c”, Ctrl+v”. Dr.Explain предлагает решение по повторному использованию контента – текстовые переменные. Это решение экономит время, когда нужно много раз использовать один и тот же текст, особенно, который может периодически изменяться – например, версия документируемой системы.

Переиспользование контента в пользовательском руководстве

Многие российские компании сталкиваются с тем, что руководство пользователя нужно писать согласно ГОСТ 19 и ГОСТ 34. Dr.Explain активирует поддержку требований ГОСТ фактически одним кликом. Программа автоматически сформирует структуру обязательных разделов и установит требуемые параметры страницы, стили абзацев, списков и заголовков.

Создание руководства пользователя по ГОСТ 34 и ГОСТ 19

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

Аннотирование скриншотов пользовательского интерфейса в руководстве пользователя

Кроме того, Dr.Explain позволяет нескольким авторам одновременно работать над проектом с использованием сервиса www.tiwri.com, учетную запись на котором можно создать бесплатно за пару минут. При внесении правок одним автором сервис блокирует редактируемые разделы проекта для изменения другими авторами.  По окончании редактирования изменения отправляются на сервер, и блокировка снимается. Так несколько человек могут одновременно работать над различными разделами проекта без риска помешать друг другу.  

Многопользовательская работа над проектом

Попробовать режим многопользовательской работы в Dr.Explain можно даже с бесплатной лицензией. Вы можете создать общий проект и полноценно работать с ним в многопользовательском режиме до семи дней.

Почему компании выбирают Dr.Explain для создания руководств пользователя

Павел Свиридов

Павел Свиридов, профессиональный военный, полковник, создатель астрологической системы “Вега Матрица”

“Только программа Dr.Explain обладала всеми необходимыми возможностями. А главное – она давала простор для творчества. Можно было выбрать цветовую гамму, вид и форму служебных элементов, настраиваемые шаблоны. Это позволило мне сохранить стилевое единство документации и самой программы. Ну, и конечно, полуавтоматическая обработка материала существенно облегчает и ускоряет работу по созданию хелпа.

Обучение работе в Dr.Explain было наглядным и сделано возможностями самой программы, что безусловно повлияло на мой выбор в ее пользу”.

Руководство пользователя к программе Вега Матрица

Прочитать полный кейс компании “Вега Матрица вы можете перейдя по ссылке

Наталья Обухова

Наталья Обухова, бизнес-аналитик компании CRM Expert

“По классике жанра был пилотный проект на двух фаворитах (Dr.Explain и HelpNDoc) и муки выбора.

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

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

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

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

Прочитать полный кейс компании CRM Expert

Николай Вальковец

Николай Вальковец, разработчик компании 2V

“Мы значительно сократили время работы техподдержки с новыми клиентами на этапе подключения. Раньше требовалось проводить онлайн презентации и видео конференции для новых клиентов, объясняя особенности программы. Сейчас же, один раз постаравшись максимально подробно всё описать, мы избавили себя и нашу техподдержку от этой работы. Нам импонирует простота программы и скорость работы. Можно быстро редактировать, добавить новые пункты в документацию, сохранить в формате HTML и выложить на сайт”.

Руководство к программе 2V Стоматология

Прочитать кейс компании V2  

Подытожим

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

Скачать Dr.Explain с неограниченной по срокам возможностью бесплатной работы можно по адресу: https://www.drexplain.ru/download/

Успешных вам разработок!

Смотрите также

  • Dr.Explain – инструмент для создания мобильной версии пользовательской документации к программным продуктам
  • Шаблоны файлов помощи, руководства пользователя программного обеспечения или сайта, шаблон базы знаний – бесплатные шаблоны и примеры пользовательской документации
Источник


Download Article


Download Article

Good software documentation, whether a specifications document for programmers and testers, a technical document for internal users, or software manuals and help files for end users, helps the person working with the software understand its features and functions. Good software documentation is specific, concise, and relevant, providing all the information important to the person using the software.[1]
 Following are instructions on how to write software documentation for technical users and end users.

  1. Image titled Write Software Documentation Step 1

    1

    Determine what information needs to be included. Software specification documents serve as reference manuals for designers of the user interface, programmers who write the code, and testers who verify that the software works as intended. The exact information depends on the program in question but may include any of the following:

    • Key files within the application. This may include files created by the development team, databases accessed during the program’s operation, and third-party utility programs.
    • Functions and subroutines. This includes an explanation of what each function or subroutine does, including its range of input values and output values.
    • Program variables and constants, and how they’re used in the application.
    • The overall program structure. For a disc-based application, this may mean describing the program’s individual modules and libraries, while for a Web application, this may mean describing which pages use which files.

  2. Image titled Write Software Documentation Step 2

    2

    Decide how much of the documentation should be within the program code and how much should be separate from it. The more technical documentation is developed within the program’s source code to begin with, the easier it will be to update and maintain along with the code, as well as to document various versions of the original application. At a minimum, documentation within the source code needs to explain the purpose of functions, subroutines, variables, and constants.[2]

    • If the source code is particularly lengthy, it can be documented in the form of a help file, which can be indexed or searched with keywords. This is a particular advantage for applications where the program logic is fragmented over many pages and includes a number of supplemental files, as with certain Web applications.
    • Some programming languages, such as Java and the .NET Framework (Visual Basic.NET, C #), have their own standards for documenting code. In these cases, follow the standards as to how much of the documentation should be included with the source code.

    Advertisement

  3. Image titled Write Software Documentation Step 3

    3

    Choose the appropriate documentation tool. To some extent, this is determined by the language the code is written in, be it C++, C#, Visual Basic, Java, or PHP, as specific tools exist for these and other languages. In other cases, the tool to use is determined by the type of documentation required.

    • Word-processing programs for Microsoft Word are adequate for creating separate text files of documentation, as long as the documentation is fairly short and simple. For long, complex text files, many technical writers prefer a documentation tool such as Adobe FrameMaker.
    • Help files for documenting source code can be produced with any help authoring tool, such as RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare, or HelpLogix.

    4. Advertisement

  1. Image titled Write Software Documentation Step 4

    1

    Determine the business reasons for your documentation. Although the functional reason for documenting software is to help users understand how to use the application, there are other reasons as well, such as assisting in marketing the software, enhancing the company image, and most notably, reducing technical support costs.[3]
     In some cases, documentation is necessary to comply with certain regulations or other legal requirements.

    • In no case, however, should software documentation substitute for poor interface design. If an application screen requires reams of documentation to explain it, better to change the screen design to something more intuitive.

  2. Image titled Write Software Documentation Step 5

    2

    Understand the audience you’re writing the documentation for. In most cases, software users have little knowledge of computers outside of the applications they use. There are several ways to determine how to address their needs with your documentation.

    • Look at the job titles your prospective users hold. A system administrator is likely expert with a number of software applications, while a data entry clerk is more likely to know only the application he or she currently uses to enter data.
    • Look at the users themselves. Although job titles generally indicate what people do, there can be considerable variation in how certain titles are used within a given organization. By interviewing prospective users, you can get a feel for whether your impressions of what their job title indicates are accurate or not.
    • Look at existing documentation. Documentation for previous versions of software, as well as functional specifications, provide some indication as to what the user will need to know to use the program. Keep in mind, however, that end users are not as interested in how the program works as they are in what it can do for them.
    • Identify the tasks needed to do the job, and what tasks need to be done before those tasks can be done.

  3. Image titled Write Software Documentation Step 6

    3

    Determine the appropriate format(s) for the documentation. Software documentation can be structured in 1 of 2 formats, the reference manual and the user guide. Sometimes, a combination of formats is the best approach.

    • A reference manual format is devoted to explaining the individual features of a software application (button, tab, field, and dialog box) and how they work. Many help files are written in this format, particularly context-sensitive help that displays a relevant topic whenever a user clicks the Help button on a particular screen.[4]
    • A user guide format explains how to use the software to perform a particular task. User guides are often formatted as printed guides or PDFs, although some help files include topics on how to perform particular tasks. (These help topics are usually not context-sensitive, although they may be hyperlinked to from topics that are.) User guides often take the form of tutorials, with a summary of the tasks to be performed in the introduction and instructions given in numbered steps.[5]

  4. Image titled Write Software Documentation Step 7

    4

    Decide what form(s) the documentation should take. Software documentation for end users can take 1 or several of many forms: printed manuals, PDF documents, help files, or online help. Each form is designed to show the user how to use each of the program’s functions, whether in the form of a walkthrough or a tutorial; in the case of help files and online help, this may include demonstration videos as well as text and still graphics.

    • Help files and online help should be indexed and keyword-searchable to allow users to quickly find the information they’re looking for. Although help file authoring tools can generate indexes automatically, it is often better to create the index manually, using terms users are likely to search for.

  5. Image titled Write Software Documentation Step 8

    5

    Choose the appropriate documentation tool. Printed or PDF user manuals can be written with a word-processing program like Word or a sophisticated text editor like FrameMaker, depending on their length and complexity. Help files can be written with a help authoring tool like RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix, or HelpServer.

    6. Advertisement

Add New Question

  • Question

    Are there any free tools for software documentation?

    Community Answer

    Try Doxygen. You comment your code, run Doxygen, and you have a webpage. Add LaTeX, and you have a PDF.

  • Question

    I have seen keypresses documented in multiple formats. Is there an actual standard for items or are they all different?

    Community Answer

    There is no universal standard; however, it is a good idea to set a standard for your own documents. For a couple of ideas, look at the Microsoft Manual of Style (available on Amazon) and the Apple Style Guide (help.apple.com/applestyleguide/). They have different styles, so if you write cross-platform documentation, you may end up using some elements from one guide and some from another.

Ask a Question

200 characters left

Include your email address to get a message when this question is answered.

Submit

Advertisement

  • The text should be arranged for easy reading, with graphics placed as close to the text that refers to them as possible. Break the documentation down into sections and topics logically. Each section or topic should address a single issue, be it a single program feature or task. Related issues can be addressed with “see also” listings or hyperlinks as necessary.

  • Any of the documentation tools listed above can be supplemented with a screenshot-creating program, such as Snagit, if the documentation requires a number of screenshots. As with other documentation, screenshots should be included to help explain how the software works, not to dazzle the user.

  • Tone is particularly important, especially when writing software documentation for end users. Address users with the second person “you” instead of third person “users.”

Thanks for submitting a tip for review!

Advertisement

Things You’ll Need

  • Software documentation tool/help authoring tool
  • Screenshot-creating tool

About This Article

Thanks to all authors for creating a page that has been read 318,464 times.

Did this article help you?

Источник

Практическая работа №25-26

   
Составление инструкции по работе с программным продуктом.

Цель работы:

–        Составить
документ «Руководство пользователю» к разработанной ранее 
программы. 

Порядок выполнения работы и отчетность.

Во время выполнения лабораторной работы необходимо соста­вить
документ «Руководство пользователю» к разработанной ранее программе.

Работа должна быть оформлена в виде документа «Руководство
пользователю».

Теоретические сведения.

Формальные требования к документации программного обес­печения
опи­са­ны в ЕСПД (Единая система программной доку­ментации), неформально:
состав документации к программному обеспечению состоит из опи­са­ния его
внешнего эффекта и описания его внутреннего устройства.

Первая часть документации, так называемая «Инструкция
пользователю» или «Руководство пользователю» предназначена для того, кто
собирается использовать программное обеспечение (для пользователя), не вникая в
подробности его внутреннего устройства.

Вторая часть – «Руководство программисту» необходима при
модификации программного обеспечения или при необходимости исправить в нем
ошибку.

В целом, документация к программному обеспечению может содержать
ниже перечисленные сведения:

1.        Наименование
ПО и описание задачи, которую оно решает.

2.                 Область
применимости ПО.

3.        Режим работы
ПО, сообщения, выдаваемые по ходу его работы, ответы пользователя на них (если
это необходимо).

4.        Исходные
данные, необходимые для работы ПО; а также выдаваемые им результаты;.

5.        Правила
подготовки исходных данных на внешних носителях (если они применяются) и вид
выдаваемой информации.

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

7.        Описания форм,
объектов. Опись свойств форм и объектов.

8.        Тексты
программ, процедур (в виде распечатки ЭВМ) с комментариями.

9.        Тесты.

10.     Инструкция (руководство)
пользователю.

Инструкция по использованию программы (или просто «Инструкция
пользователю», или «Руководство для поль­зователя») – это выдержка из полной
документации, предназ­наченная для эксплуатации программы. Она представляет
собой независимый документ для пользователя программы, в котором описы­вается:
что делает программа и как им поль­зоваться.

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

Первая часть инструкции является описательной и должна
содержать:

–    наименование программы;

–    краткое описание программы;

–    перечень выполняемых программой
функций;

–    краткую характеристику метода (или
методов) решения поставленной задачи, его досто­инство и недостатки;

–    полную библиографическую ссылку на
полное описание  метода;

–    описание входных и выходных данных.

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

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

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

–    как запустить программу;

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

–    подготовка и ввод исходных данных в
программу;

–    как реагировать на запросы программы;

–    как вести работу в исключительных
ситуациях;

–    как реагировать на ошибки;

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

–    как получить требуемый результат;

–    как правильно закончить работу с
программой (запланированный программой выход);

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

Источник

14.07.2014

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

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

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

Метод 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.

(продолжение следует)

Источник: How to Write Software Documentation

Тэги: инструкции, инструменты, советы

< Вернуться к списку публикаций

  • API
  • DITA
  • Flare
  • HTML
  • MadCap
  • MS Word
  • PDF
  • XML
  • Алисса Фокс
  • Марк Бейкер
  • ПроТекст
  • Том Джонсон
  • анализ
  • блоги
  • веб-контент
  • видеоролики
  • единый источник
  • изображения
  • инструкции
  • инструменты
  • исследование
  • качество контента
  • командная работа
  • конференции
  • локализация/перевод
  • минимализм
  • навыки
  • обучение
  • опыт
  • организация работы
  • продвижение
  • профессия
  • редактирование
  • роли
  • советы
  • стиль
  • структурированное писательство
  • теория документирования
  • управление контентом
  • форматирование
  • форматы
  • ценность контента
  • эджайл
  • эффективность
  • юмор

Облако тегов

Источник

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

Время на прочтение
8 мин

Количество просмотров 12K

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

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

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

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

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

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

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

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

Это гусь Гоша и его постоянно отвлекают техническими вопросами

Это гусь Гоша и его постоянно отвлекают техническими вопросами

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

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

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

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

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

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

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

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

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

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

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

Результаты:

  • 5 баллов: у вас хорошая документация, автор вами гордится!

  • 0–4 балла: есть что доработать — переходите к практическим шагам.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

✅ Удачно: позвать на встречу или созвон эксперта из команды (обычно это тимлид или старший разработчик) и вычитать с ним весь материал полностью, не поверхностно.

❌ Неудачно: скинуть материал эксперту и попросить его самого удалить лишнее.

Если плохо выполнить этот шаг, вы потратите много времени зря в будущем. Проверено мной.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Неудачные варианты

Удачные варианты

«Пушка», «долбилка» и «стрелялка»;
Почему: кажется, что это разные термины, возникает путаница. Не найдётся по Ctrl+F.

«Пушка»

Почему: все коллеги в Ozon знают этот термин.

«СronJob’ы», «кроны» и «джобы»;
Почему: неясно, составляющие это друг друга или одно и то же. Не найдётся по Ctrl+F.

«CronJob»

Почему: все коллеги знают этот термин, он цельный.

«Фэктори» и «фабрика», «эккаунт» и «аккаунт», «экшен» и «действие»
Почему: будьте осторожны с англицизмами. Не используйте их, если есть подходящий термин на русском языке. Не найдётся по Ctrl+F.

«Фабрика», «аккаунт» и «действие»

Почему: популярные, понятные всем термины на русском языке.

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

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

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

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

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

Если не договориться «на берегу», документация всегда превращается в хаос:

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

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

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

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

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

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

  • нет архива;

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

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

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

  1. Черновик статьи создавайте в папке для черновиков.

  2. Не добавляйте статью в список публичных, пока не допишете.

  3. Чтобы перенести статью в список публичных:

  • отправьте её в чат команды;

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

  • решите с командой, в какой раздел её перенести.

  1. Статью можно переносить.

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

Шаг 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.

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

Итог

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

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

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

Источник

Добавить комментарий