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

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

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

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

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

1. Скука убивает
2. Прежде чем начать, выясните точно для себя, какие действия вы ожидаете от читателя, осилившего ваш труд
3. Пишите в соответствии с правильно сформированной структурой
4. Избегайте неоднозначных местоимений
5. Ясность = иллюстрации + слова
6. Когда имеете дело с понятиями, концепциями и т.п., используйте логическую иллюстрацию и пример
7. Не опасайтесь переделок

1. Скука убивает

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

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

Мне нравится юмор, поэтому я стараюсь сделать мои литературные технические «творения» забавными, но, конечно, без ущерба для ясности. Пытаюсь разговаривать с читателем, а не поучать его. Пишу о делах, которые, действительно, имеют значение для меня. Широко использую иллюстрации, чтобы предотвратить неясность для читателя.

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

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

Техническая документация полностью завязана на последующее поведение читателя. Читатель затрачивает своё время на чтение вашего творения, потому что он или она имеет намерение сделать что-то после завершения процесса чтения. Этим «что-то» может быть выпечка печенья с кусочками шоколада, остановка ядерного реактора или разработка кластера Hadoop. Важно помнить, что читатель использует ваше описание как средство для выполнения другого процесса. Ваш труд является неким проводником к дальнейшему вполне определённому поведению.

Поэтому чрезвычайно полезно для вас чётко определиться, какие действия вы ожидаете от читателя после завершения процесса чтения. Изложите ваше намерение с самого начала. Не оставляйте читателя гадать. Ваше заявление может быть простым и очевидным, как, например: «после прочтения данной статьи вы сможете [впишите свой вариант]». Если вы определились с действиями, ожидаемыми от читателя после прочтения, то процесс написания будет для вас легче с самого начала.

3. Пишите в соответствии с правильно сформированной структурой

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

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

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

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

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

Листинг 1: неправильно сформированная структура

1. Приготовление апельсиново-клюквенно-мандаринового шипучего напитка

1.1. Шаги, требуемые для приготовления шипучего напитка

1.1.1. Подготовка ингредиентов

1.1.2. Смешивание ингредиентов шипучего напитка

1.1.3. Подача шипучего напитка

Обратите внимание, что в листинге 1 уровень 1 имеет одиночный подуровень: «1.1. Шаги, требуемые для приготовления шипучего напитка«. Такая структура является нарушением первого правила. Чтобы подуровень был правильно сформирован, в разделе должна быть, как минимум, ещё одна позиция. Другими словами, это значит, что на любом данном уровне должно быть, как минимум, два подуровня.

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

Может возникнуть вопрос: «Где раздел Шаги, требуемые для приготовления шипучего напитка». Видно, что этот раздел теперь не является позицией структуры, а перешёл в контент исходного раздела, как показано в листинге 2 внизу.

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

1. Приготовление апельсиново-клюквенно-мандаринового шипучего напитка

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

1.1. Подготовка ингредиентов

1.2. Смешивание ингредиентов шипучего напитка

1.3. Подача шипучего напитка

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

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

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

1. Приготовление шипучего апельсиново-клюквенно-мандаринового напитка

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

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

1.1. Подготовка ингредиентов

1.2. Смешивание ингредиентов шипучего напитка

1.3. Подача шипучего напитка

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

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

4. Избегайте неоднозначных местоимений

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

Рассмотрим абзац в листинге 4.

Листинг 4: абзац с неоднозначными местоимениями

Трафальгаборы являются базовой компонентой фрейма Вибитатов. Эта статья показывает, чем они являются и как их использовать.

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

Применительно к абзацу вверху я не удивлюсь, если вы спросите: «Что это за штука „Трафальгабор“? А что такое „Вибитата“? О чём, вообще, этот абзац? О том, как использовать Трафальгаборы? Или о том, как использовать Вибитаты? Или о том, как использовать и те, и другие? Бред какой-то. Вернусь я лучше на свою страницу в Фейсбуке».

Если читатель при чтении вашего описания вынужден тратить время на выяснение, что же вы пытаетесь ему сообщить, то мало того, что информативный поток будет нарушен, но и читатель, скорее всего, будет запутан. Как только вы привели читателя в замешательство, вы его потеряли. Всё другое в мире, направленное на привлечение внимания вашего читателя, становится для него более притягательным, чем ваше творение. Щелчок по кнопке «Далее» — и ваша работа остаётся непрочитанной.

В листинге 4 замешательство порождается неоднозначным использованием местоимения «они» во втором предложении. К чему относится здесь «они» — к Трафальгаборам, Вибитатам или к обоим? Помните, что читатель ничего не знает, что такое Трафальгаборы или Вибитаты. (См. рис. 1 внизу.)

Рис. 1. Использование неоднозначных местоимений запутывает техническое описание

Решение проблемы простое. Посмотрите листинг 5 внизу. Неоднозначное местоимение удалено. Ясность восстановлена.

Листинг 5: устранение неоднозначных местоимений

Трафальгаборы являются базовой компонентой фрейма Вибитатов. Эта статья рассказывает, что такое Трафальгаборы и как их использовать.

Осторожно! Неоднозначное использование местоимений ведёт к техническому описанию, приводящему в замешательство.

5. Ясность = иллюстрации + слова

Посмотрите на фотографию внизу. Скажите, если сможете, о чём это фото?

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

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

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

Рис. 2. Инструменты и ингредиенты, требуемые для приготовления апельсиново-клюквенно-мандаринового шипучего напитка

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

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

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

Примечание: глаз привлекают изображения

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

6. Когда имеете дело с понятиями, концепциями и т.п., используйте логическую иллюстрацию и пример, логическую иллюстрацию и пример

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

Применим это правило для описания понятия элементарной алгебры.

Понятие «транзитивность отношения равенства» представляет собой следующее:

если A = B и B = C, то A = C;

Теперь приведём логическую иллюстрацию, описывающую это понятие (см. рис. 3).

Рис. 3. Транзитивность отношения равенства является фундаментальным принципом элементарной алгебры

Листинг 6 ниже показывает несколько конкретных примеров для закрепления понимания рассматриваемого положения.

• Если 7 = 3 + 4 и 3 + 4 = 5 + 2, то 7 = 5 + 2;
• Если 12 + 5 = 7 + 10 и 7 + 10 = 6 + 11, то 12 + 5 = 6 + 11;
• Если x + y = z и z = 2a, то x + y = 2a.

Теперь рассмотрим понятие, которое ближе к разработке программного обеспечения и несколько труднее для понимания. Таким понятием является наследование моделей объектов проекта (POM = Project Object Model) в Maven (система автоматизированной сборки проектов). Пример 1 ниже представляет рассматриваемое понятие и даёт логическую иллюстрацию, описывающую это понятие. В конце представлена ещё одна иллюстрация, показывающее конкретное использование POM-файлов в ситуации наследования.

Пример 1: выдержка из технического описания наследования моделей объектов проекта (POM) в Maven (система автоматизированной сборки проектов)

Представление наследования POM-файла

POM-файл является XML-файлом, используемым для описания Maven-проекта и для работы с этим проектом. Можно задать, чтобы некоторый Maven-проект наследовал настройки из отдельного родительского POM-файла. Способность наследовать настройки из родительского POM-файла называется POM-наследованием. Вы используете элемент

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

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

Рис. 4. Можно назначить мастер-файл РОМ, из которого будет происходить наследование общих настроек

Рис. 5 ниже показывает содержание POM.xml-фалов для Maven-проектов stooges-web, stooges-api и stooges-dal. Каждый проект сконфигурирован на использование элемента

для наследования настроек из stooges-project.

Рис. 5. Использование элемента

для управления Maven-проектом с целью наследования настроек из внешнего РОМ-файла

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

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

7. Не опасайтесь переделок

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

Можно сказать об этой работе, перефразируя известную цитату Томаса Эдисона: «Написание технического текста — это на 10% литературное творчество и на 90% переработка!»

Обещанный бонус

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

1. Составляю структуру, как минимум, до второго уровня (если удаётся, то и до третьего);
2. Добавляю иллюстрации в структуру для каждого понятия;
3. Делаю подписи под иллюстрациями;
4. Пишу текст в соответствии со структурой, соблюдая правило двух предложений и подстраивая структуру под текст;
5. Редактирую, переделываю;
6. Отправляю результат специалисту по рассматриваемой теме на рецензирование (специалистом по рассматриваемой теме является лицо, которое в состоянии выявить неточности и неясности в описании);
7. Снова редактирую работу на основе отзыва рецензента (рецензентов).

И вот они у вас: 7 правил, 7 шагов. Кому-то надо больше? Теперь, когда вы знаете все мои приёмы, двигайтесь свободно вперёд и делайте мир более правильным, привлекательным, ясным и интересным местом для жизни. Он заслуживает таких усилий.

• техдокументация
• техническая документация
• технический текст
• документация
• подготовка документации

• Учебный процесс в IT
• Подготовка технической документации

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

На проекте нет технической документации: с чего начать

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

В сегодняшней статье — ответ от Павла Устинова , спикера курса TechMind, PMO в компании SOLAR Digital.

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

Проект есть, а документации нет: разбираем причины

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

Проект динамично развивается и активно разрабатывается

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

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

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

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

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

Начните с таких документов:

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

Пример с Filters и Filter-Port

Filters

Пользователь должен уметь фильтровать по различным параметрам и данным в таблице. Множественный выбор по одному фильтру должен работать, как логическое AND, т.е. если пользователь выбрал Hong Kong и Kyiv, выборка отдаст результаты только по пересечению условий, а именно, в таблице будет отображены данные только для порта Hong Kong и только для порта Kyiv.

Filter-Port

Пользователь может фильтровать по портам, может применять множественный выбор портов, в самом фильтре присутствует поиск. Список портов содержит только те порта, в которых есть терминалы. Множественный выбор по одному фильтру должен работать, как логическое OR, т.е. если пользователь выбрал Hong Kong и London, выборка отдаст результаты по обоим портам. Выбранный порт, или несколько, отображаются в дополнительной строке, как теги. Пользователь может убрать один или все теги и, как результат, фильтрация по ним отменится.

Проект сделан плохо в плане архитектуры

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

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

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

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

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

Сколько нужно документов и кто их должен создавать

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

Архитектура

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

Разработчики могут отказываться документировать, если:

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

Главное — победить возражение, что «документацию писать очень долго, это пустая трата времени, зачем, все ж и так понятно». В любом случае, нужно описать из чего состоит приложение (классы, модули/микросервисы), что общается с базой данных, файлами, как устроена передача данных на front-end.

Общие условия работы

Укажите общие условия (Developers Agreement), какой style guide, как использовать переменные (variables), функции (functions / classes methods), классы, какой code linting (если он есть), какой подход используется к организации кода (SOLID), как общаются между собой функции (functions interacting). Не должно быть сомнений, что все будет одинаково, хотя на практике так бывает далеко не всегда.

Другая базовая документация:

• Технический стек проекта
• Инструкции по установке на окружение: local environment and server environment.
• Описание работы CI/CD, если он есть и по возможности, его настройки (setup). Указать, какие скрипты что делают.
• Внешние интеграции: какие есть, как они работают. Приложить ссылки на API документацию.

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

• Структура базы данных (выгружается из веб-шторма автоматически) или просто перечисление таблиц и зачем нужны.

• Если есть unit тесты — дать перечисление, какие есть.
• API Doc, если используете API. API Doc надо иметь подробный, с описанием методов API, параметров и структур ответов с типами данных в нем.

Остальное по вкусу и необходимости, например:

• Инструкции пользователя
• Тест-кейсы, где перечислено все, что тестируется.
• Описание функциональности приложения

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

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

В чем писать техническую документацию: 5 удобных программ

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

⇣ Содержание

• Clarify 2.0.5 – быстрые мануалы без дополнительного софта
• Dr.Explain 5.3 – полуавтоматические руководства с готовыми аннотациями
• Manula – перенос мануалов в онлайн
• StepShot – снимет, расставит по порядку и подпишет
• iorad – аналог StepShot, но в браузере
• Заключение

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

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

⇡#Clarify 2.0.5 – быстрые мануалы без дополнительного софта

• Разработчик:Blue Mango Learning Systems.
• Операционная система: Windows/Mac.
• Распространение: shareware, $30.
• Русский интерфейс: нет.

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

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

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

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

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

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

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

Над проектами Clarify можно работать совместно с другими пользователями. Для этого нужно создать учетную запись на сайте Clarify-it.com. Кроме этого, программа поддерживает сервисы Dropbox и Evernote, дает возможность экспортировать проекты в PDF, Word, HTML и на сайты WordPress. При желании можно также просто скопировать весь текст документа (или же текст с картинками) в буфер обмена.

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

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

⇡#Dr.Explain 5.3 – полуавтоматические руководства с готовыми аннотациями

• Разработчик: Indigo Byte Systems.
• Операционная система: Windows.
• Распространение: shareware, от 7 500 рублей.
• Русский интерфейс: есть.

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

Если в интерфейсе захватываемого приложения встретится меню, Dr.Explain обязательно раскроет его, сделает снимок всех уровней подменю и добавит выноски для каждого элемента. Более того, все скриншоты будут помещены в проект Dr.Explain с сохранением структуры документа (то есть, скажем, основное окно будет в разделе 1, раскрытое меню – 1.1, а пункты подменю – 1.1.1, 1.1.2 и так далее). Таким образом, вся скучная и монотонная работа выполняется в автоматическом режиме, и пользователю остается только добавить описание всех элементов интерфейса. Понятное дело, что структуру документа можно изменять, перемещая пункты, добавляя новые и удаляя ненужные.

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

Если ранее работа над документацией велась в другом приложении, можно легко импортировать проект и программу. Dr.Explain поддерживает импорт документов CHM, Word, HTML, HLP, RTF, TXT, XML.

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

Для экспорта готовой документации предлагаются форматы CHM, Word, HTML и PDF. При этом еще до выполнения экспорта можно увидеть, как мануал будет выглядеть в одном из этих форматов. Перед экспортом нужно не забыть перейти в настройки проекта и задать дополнительные параметры. Например, при сохранении документа в PDF можно указать ключевые слова, автора, заголовок, тему и формат, настроить колонтитулы и нумерацию страниц, а также создание закладок для разделов. При экспорте в HTML есть возможность настроить карту сайта, добавить комментирование для пользователей Facebook✴ и Disqus, включить показ панели с кнопками социальных сетей, указать данные FTP-сервера, на который будет загружен проект.

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

⇡#Manula – перенос мануалов в онлайн

• Разработчик: Bitz & Pixelz.
• Операционная система: любая.
• Распространение: по подписке (от $10 в месяц).
• Русский интерфейс: нет.

В начале 2009 года Альвин Хогердайк (Alwin Hoogerdijk), создатель семейства приложений для учета коллекций Collectorz.com, решил создать для своих программ онлайновую справку. Ему надоело, что часто приходится откладывать выпуск новых версий программ из-за того, что еще не готовы изменения в пользовательской документации, или же, наоборот, делать новые релизы доступными для скачивания с устаревшими справочными файлами, а затем выпускать новые билды, в которых обновлены только мануалы.

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

Manula.com дает возможность создавать и обновлять мануалы в браузере, без необходимости использования настольных приложений. Главное преимущество онлайнового мануала – мгновенное обновление. Как только разработчики внесли в него изменения, обновленные справочные файлы уже становятся доступны пользователям — не надо ничего никуда экспортировать, загружать на сервер HTML-файлы и так далее. При этом мануалы смотрятся одинаково хорошо на любых устройствах – на больших мониторах, планшетах или смартфонах. Сервис автоматически выполняет адаптацию под размер экрана.

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

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

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

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

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

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

⇡#StepShot – снимет, расставит по порядку и подпишет

• Разработчик: StepShot.
• Операционная система: Windows.
• Распространение: по подписке ($29 в месяц). Есть полнофункциональная триал-версия на 14 дней, которая затем становится ограниченной.
• Русский интерфейс: нет.

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

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

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

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

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

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

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

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

Добавление описаний тоже максимально автоматизировано. Поскольку при написании технической документации чаще всего используются одни и те же словосочетания, программа снабжает скриншоты описаниями вроде «Click on «Skype» button». Для этого она захватывает названия элементов интерфейса, распознает их и затем добавляет в подпись под картинкой. Работает это, правда, только для английского и парочки других европейских языков, а составителям русскоязычной документации придется добавлять все описания вручную.

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

После того как работа над созданием руководства завершена, можно экспортировать его в один из нескольких поддерживаемых форматов: документ Word, PDF, HTML, DITA или XML. При этом для Word доступно несколько разных шаблонов.

Также есть прямая публикация на WordPress и в Confluence, а все изображения, использованные в проекте, предлагается сохранить в одной папке. К сожалению, при этом можно управлять только качеством картинок, а вот менять названия нельзя. Скриншоты сохраняются с названиями типа image0001.jpg, image0002.jpg, что не всегда удобно (было бы неплохо, если бы была возможность именования изображений на основе заголовков в проекте).

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

⇡#iorad – аналог StepShot, но в браузере

• Разработчик: iorad inc.
• Операционная система: любая.
• Распространение: по подписке ($90 в месяц). Есть ограниченная бесплатная версия.
• Русский интерфейс: нет.

Для начала работы с iorad нужно установить расширение для Google Chrome и открыть веб-страницу, действия на которой должны быть задокументированы. После этого автору нужно нажать на кнопку расширения. В веб-сервисе iorad применён тот же подход, что и в StepShot (автор инструкции выполняет все действия, сервис их сохраняет, разбивает на шаги, которые затем можно отредактировать и опубликовать в виде урока). Однако iorad работает как расширение к браузеру, и все действия по обработке, редактированию и публикации пошаговых инструкций выполняются на сервере. С одной стороны, это удобно, так как сервис доступен на любой платформе, однако есть досадное ограничение – с помощью iorad можно записать только действия, выполняемые в браузере. То есть сервис подходит только для создания мануалов веб-приложений, а для настольных программ не годится.

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

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

Каждый урок начинается предложением «The first step is to open [название вебс-страницы]», а заканчивается фразой «That’s it. You’re done.» Несмотря на то, что описания автоматически составляются только на английском, в готовой инструкции есть возможность увидеть их на других языках за счет интеграции с переводчиком Google. Если не добавлять пространных описаний, а ограничиться простыми фразами, такой перевод работает сносно.

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

Что касается инструментов для редактирования снимков экрана, то тут создателям iorad еще есть над чем работать. Все, что может делать пользователь, это смазывать часть изображения, а также изменять размер и местоположение рамки для выделения.

Готовые инструкции могут быть сохранены в виде файлов Word Doc, PowerPoint и PDF, а также внедрены на сайты или просмотрены в браузере на любых платформах, как настольных, так и мобильных. Используя последние два варианта, можно оценить главное преимущество iorad – интерактивность. Инструкция, полученная с помощью сервиса, запускается в специальном плеере. Пользователь может выбрать один из вариантов работы с ней: просмотр или же самостоятельное повторение всех шагов.

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

⇡#Заключение

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

Работая над документацией, стоит всегда помнить о «принципе Златовласки»: пользователю надо давать не слишком много информации, не слишком мало, а в точности столько, сколько нужно для выполнения задач. Хорошая документация должна работать как навигатор: как только пользователь показал, в каком месте он находится (с какой проблемой столкнулся), он тут же должен при помощи файла справки отыскать правильный путь (решение проблемы). И конечно, не стоит забывать о гиперссылках, при помощи которых нужно обеспечивать свободное перемещение пользователя по мануалу. Если в его руках подробнейший PDF на 100 страниц, в котором нет никаких ссылок, качество такой документации вряд ли может оценить кто-то, кроме ее составителя.

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