Как сделать техническая руководство

Пишем техническую документацию: руководство для непрофессионала

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

В этом году я многому научилась в сообществе Write The Docs, у других провайдеров API, а также методом проб и ошибок. В прошлом году я поделилась опытом в докладе «Что мне хотелось бы знать о написании документации» на конференции API Strategy and Practice в Портленде. Эта статья — обзор полученных знаний.

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

«Нация содрогается от большого фрагмента слитного текста», фото The Onion

Знаете это чувство, как на картинке? Так бывает. Может и не физически, но, скорее всего, люди содрогаются умственно. Меня постоянно мучала мысль, что люди не будут читать мои тексты, если я не оформлю их легко усваиваемым способом. Чёрт возьми, такое может произойти даже с этой статьёй.

В исследовании направления взгляда Neilson Norman Group в 2006 году 232 пользователя просмотрели тысячи веб-страниц. Оказалось, что пользователи обычно смотрят на страницы по F-шаблону:

1. «Сначала читают в горизонтальном направлении, как правило, в верхней части области с контентом. Это верхний элемент фигуры F».
2. «Затем немного перемещаются вниз по странице — и совершают второе горизонтальное движение, которое обычно охватывает более короткую область, чем предыдущее. Этот дополнительный элемент образует средний элемент фигуры F».
3. «Наконец, пользователи сканируют левую сторону контента по вертикали. Иногда это медленное и систематическое сканирование, которое отображается в виде сплошной полосы на теплокарте. Иногда движение более быстрое, образующее пятна на теплокарте. Это последний вертикальный элемент в фигуре F».

Теплокарты Nielsen Norman Group

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

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

Каковы конкретные последствия для документации?

• В первых двух абзацах следует указать самую важную информацию
• Критически важны первые 3−5 слов
• Заголовки, абзацы и маркированные списки с информативными словами
• Изменения шрифта (размер, ссылки, выделения жирным и т. д.) могут быть необходимы, чтобы удержать внимание читателя

Так как структурировать контент на странице?

• Предотвратите сканирование: убедитесь в выделении информации, которая нужна читателю
• Одна мысль на абзац. Если их несколько, разбейте абзац
• Пользователи пропускают всё, что похоже на баннеры, поэтому будьте осторожны с иллюстрациями
• Не расширяйте слишком сильно колонку с текстом: оптимально 65−90 символов

Некоторые из этих советов я узнала из лекции Кевина Берка «Как писать документацию для пользователей, которые её не читают». Кевин поддерживал документацию Twilio с 2011 по 2014 годы.

Кроме того, у абзацев есть своя специфика. Подобно слитному тексту The Onion, когда вы читаете много абзацев, можно пропустить суть. Тогда зачем использовать их так часто? Давайте проведём эксперимент из документации Keen IO:

Быстро прочитайте это:

У наборов событий может быть практически любое название, но есть несколько правил: в названии должно быть не более 64 знаков. Оно должно содержать только символы ASCII. Оно не может быть значением null.

Теперь быстро прочитайте это:

У наборов событий может быть практически любое название, но есть несколько правил:

• В названии должно быть не более 64 знаков
• Оно должно содержать только символы ASCII
• Оно не может быть значением null

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

Позже мы подробнее обсудим вёрстку документации и навигацию по ней.

Примеры кода

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

Контекст в примере кода важен для успеха разработчика. Разработчики любят быстро копировать и вставлять. Вот пример с Keen IO API:

var client = new Keen({
  projectId: "your_project_id",
  writeKey: "your_write_key"
});

var ticketPurchase = {
  price: 50.00,
  user: {
    id: "020939382",
    age: 28
  },
  artist: {
    id: "19039",
    name: "Tycho"
  }
}

client.addEvent("ticket_purchases", ticketPurchase);

Разработчик быстро копирует и вставляет этот код. И…

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

Хорошо, они запустили его и… ReferenceError: Keen is not defined. Клиент Keen не инициировался, в верхней части нет оператора import или require, и он работает только после установки библиотеки npm.

Пользователь всё починил и запустил ещё раз… Угадайте?! Ещё одна ошибка! your_project_id и your_write_key отсутствуют.

Всё это можно было бы сделать более очевидным.

Вот пример из документации Twilio, которая предоставляет хороший контекст для конечного пользователя:

Скриншот из документации библиотеки Twilio Node Helper

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

Копипаст багов

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

# Скопируйте и вставьте следующую команду
$ gem install rails

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

bash: command not found: $

Распространённая ошибка. Либо вы хотите, чтобы команда выглядела как в командной строке, либо вы случайно её скопируете. Я бы рекомендовала отказаться от $. Ещё можно найти способ запретить копипаст этого символа, чтобы ошибка не раздражала пользователей.

Более свежий пример: вы проверяли, насколько легко выделить код, который пользователь хочет скопировать?

Келси Хайтауэр изо всех сил пытался скопировать образец кода из StackOverflow на презентации Google Cloud Next.

«Хорошие программисты копируют, великие программисты вставляют»

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

«Вот и всё!»

«Вот и всё!» Фраза кажется довольно безобидной вне контекста, но представьте, как воспринимаются определённые слова вроде «легко», «просто», «тривиально» и «несложно», когда у вас проблемы — не здорово! Когда человек застрял, пытаясь заставить API работать, такая фраза подвергает сомнению его интеллект и заставляет задать вопрос: «Значит, я глупый?» Это деморализует.

Чрезмерное упрощение

Упрощение встречается повсеместно. Оно наиболее распространено среди новичков в написании документации. Зачастую авторы документации — одновременно и разработчики системы, поэтому некоторые вещи им кажутся «лёгкими». Но ведь они разработали эту функцию, написали для неё код, проверили много, много раз, а потом написали документацию. Когда вы делаете что-то десятки раз, то ясное дело, что это будет «легко» для вас. Но как насчёт того, кто никогда раньше не видел UI или функцию?

Сопереживание

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

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

• Попросите менее опытных участников проекта честно прокомментировать документацию
• Поощряйте менее опытных участников проекта вносить свой вклад или указывать на пункты документации, которые они не понимают
• Создайте окружение, где поощряются вопросы, в том числе такие, какие могут показаться «очевидными» для опытных участников проекта — это поможет заметить «слепые зоны»
• В процессах код-ревью и CI используйте линтеры, чтобы гарантировать эмпатию и дружественность языка для всех пользователей
• Наконец, попросите прокомментировать документацию реальных пользователей, покажите им текст и спросите, всё ли понятно

Сообщения об ошибках как вид документации

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

Кейт на сайте Write The Docs рассказывает много полезного о написании сообщений об ошибках. Многое я узнала во время прошлой работы над сообщениями об ошибках API, а также будучи на другой стороне баррикад, получая сообщения об ошибках других API в качестве разработчика.

Кейт говорит, что хорошие сообщения об ошибках построены на трёх принципах:

• Скромность
• Гуманность
• Полезность

Скромность

Сразу нужно извиниться, даже если это не ваша вина. Это я практикую также в службе поддержки.

Пример:

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

Гуманность

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

Пример (ошибка кода состояния 401 у Twilio):

{ 
    “code”: 20003,
    “detail”: “Your AccountSid or AuthToken was incorrect.”,
    “message”: “Authenticate”,
    “more_info”: “https://www.twilio.com/docs/errors/20003",
    “status”: 401
}

Полезность

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

Пример:

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

Как писать сообщения об ошибках

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

Плохой пример:

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

Хороший пример:

Чтобы вернуться на предыдущую страницу, используйте кнопку «назад».

Сообщения об ошибках в документации

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

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

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

Источник: https://www.twilio.com/docs/api/errors

Stripe делает нечто подобное с детальным описанием различных кодов ошибок.

Источник: https://www.twilio.com/docs/api/errors

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

Подсказка: если кто-то не ответил скромно, по-человечески и с пользой, то с достаточной «репутацией» можно редактировать ответы StackOverflow.

Выбор слов

У многих слов есть устоявшиеся ментальные модели. Например, такие слова, как «библиотеки», SDK, «обёртки» и «клиенты» уже перегружены и проходят мимо внимания читателя.

В своей лекции «Даже для этой лекции трудно подобрать название» на Write The Docs Рути Бендор говорит, почему выбор правильных слов может быть таким трудным.

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

В такой ситуации как никогда справедлива известная поговорка: «Есть только две трудные задачи в области информатики: инвалидация кеша и придумывание названий». Цитату часто приписывают Филу Карлтону, но сегодня ходит много вариантов этой поговорки. Иногда в конце добавляют «… и ошибка на единицу». Рути считает это демонстрацией, что программное обеспечение в наши дни во многом основано на чужом коде или работе.

Почему же сохраняются плохие названия объектов (или документация)?

Как и с чрезмерным упрощением, мы часто не понимаем, что название плохое. Это то, что Рути называет сбоем эмпатии. Это как сказать, что проблема неудачных слов меня не касается, поэтому её не существует.

Подсказка для США: во избежание случайного расизма используйте слова «запрещённый список» и «разрешённый список» вместо «чёрный» и «белый».
(Источники: Андре Штальц и rails/rails/issues/33677)

Мне это ещё напоминает то, что Рути называет ошибкой мышления новичка. Это как сказать «Мне это совершенно ясно. Не понимаю, как кто-то не может этого понять».

Наконец, Рути упоминает ошибку локализации. Например, слово Bing по-китайски означает «больной».

Согласно исследованию GitHub Open Source Survey за 2017 год:

Почти 25% разработчиков читают и пишут по-английски не «очень хорошо». При общении в проекте используйте понятный и доступный язык для людей из неанглоязычных стран.

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

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

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

• Привязаны к ней
• Не находим времени
• Не видим важности
• У нас нет агентства, чтобы её исправить

Вы можете сказать или услышать: «Но это моё детище!», «Кто убрал мою конфетку?» «Если мы переименуем, всё сломается», «Не верю, что изменение этого названия повлияет на что-то важное».

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

Как правильно подобрать слова?

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

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

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

С другой стороны, хорошие названия:

• способствуют внезапному прояснению («вот оно что!»)
• вводят в контекст
• объясняют
• освещают
• оказывают поддержку

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

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

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

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

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

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

* Внесена в перечень общественных объединений и религиозных организаций, в отношении которых судом принято вступившее в законную силу решение о ликвидации или запрете деятельности по основаниям, предусмотренным Федеральным законом от 25.07.2002 № 114-ФЗ «О противодействии экстремистской деятельности».

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

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

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

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

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

Принципы разработки руководства по эксплуатации (РЭ)

Руководство по эксплуатации в большинстве случаях разрабатывается на основе положений Государственного стандарта Р 2.601-2019. В ГОСТе представлено подробное описание документа, а также особенности его разработки и правильного оформления.

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

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

В ГОСТе указано, что РЭ может быть доступно в электронном варианте. А это в свою очередь даёт возможность производителям добавить документ на сайт, дополнив его анимацией для более лёгкого восприятия пользователями. Согласно ГОСТу технический паспорт можно объединить с руководством по эксплуатации. А всё по причине минимальных отличий в содержаниях. Если компания-изготовитель  объединяет эти два документа в один, то и названием соответственно меняется на «Паспорт и руководство по эксплуатации».

Какие правила используются для разработки документа

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

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

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

Инструкция по эксплуатации

1. Вводная часть;
2. Отличительные особенности функционирования;
3. Использование по назначению;
4. Техническое обслуживание;
5. Работы по ремонту в текущее время;
6. Правила хранения;
7. Транспортировка;
8. Особенности утилизации.

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

Документы, необходимые для руководства

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

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

• Технические документы рабочего плана;
• Схемы;
• Чертежи;
• Информация о техническом состоянии;
• Протоколы приёмки с итогами испытаний, которые были проведены;
• Сведения об уровнях мощности производства.
• Документы, необходимые для определённой техники в зависимости от особенностей.

Согласно требованиям государственного стандарта 2.601-2006 составление руководства по эксплуатации не является обязательным критерием для всех видов продукции. Нужна ли разработка документа определяет сам производитель изделий исходя из особенностей технического применения, наличия дополнительной информации для правильной настройки и других критериев. Однако в ГОСТе оговаривается, что в случае, если составление руководства по эксплуатации заказано со стороны Министерства обороны Российской Федерации, то именно данный орган и будет решать, необходимо ли разрабатывать соответствующий документ.

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

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

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

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

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

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

В каких случаях нужен документ?

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

Наличие руководства нужно не только для безопасной эксплуатации техники – оно также потребуется для проведения оценки соответствия устройства в рамках системы ТР ТС или ГОСТ Р.

Получить руководство можно, основываясь на положениях приказа Ростехнадзора №112, утвержденного и принятого 29.02.2008 г. Инструкция позволяет дать представление пользователям и потребителям данной категории продукции о правилах ее использования, сфере применения и особенностях работы.

Нормативная база

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

• ГОСТ 2.105-2006 – в стандарте отражены нормы и требования в отношении содержания текстовой части.
• ГОСТ 2.601-2006 – стандарт, который регулирует правила оформления.

Кроме того, требования к содержанию и составлению документов, которые разрабатываются в отношении различных машин, отражены в действующих технических регламентах (например, ТР ТС 010/2011).

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

Структура инструкции по эксплуатации

1.   Введение.
2.   Описание и особенности функционирования.
3.   Применение по назначению.
4.   Техническое обслуживание.
5.   Текущие ремонтные работы.
6.   Особенности хранения.
7.   Транспортировка.
8.   Правила утилизации.

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

Порядок разработки

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

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

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

Срок и необходимые документы

Каждому руководству присваивается название и буквенное/цифровое обозначение. Выдается документ на срок до 5 лет. Таким образом, пересмотр РЭ осуществляется не реже одного раза в 5 лет. Если на протяжении периода его действия условия функционирования и применения изделий остались неизменными, его действие продлевается на аналогичный срок.

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

1.   Рабочая техническая документация.
2.   Чертежи и схемы.
3.   Сведения о техническом состоянии.
4.   Протоколы и акты приемки с результатами проведенных испытаний.
5.   Информация о производственных мощностях изготовителя и другие документы (в зависимости от особенностей конкретной техники).

Чтобы ознакомиться с дополнительными сведениями, обратитесь в центр сертификации «Рос-Тест». Заказать любой технический или конструкторский документ можно прямо на нашем официальном сайте.

 vlada_maestro / shutterstock

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

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

Содержание

• Два вида документации
• Правила хорошего тона в составлении документации
• Где писать документацию в C#
• Как создать файл документации
• Заключение

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

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

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

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

1. Документация нужна не всегда

Если программа одноразовая, не стоит тратить время на написание пояснений. Например, если нужен небольшой скрипт, который будет написан за пять минут и использован 1-2 раза.

2. Документация нужна не везде

Также не нужно писать пояснения ко всему. Если код написан хорошо, то по названиям уже будет понятно, что это такое и зачем оно используется. Например, легко догадаться, что метод int Sum (int a, int b) возвращает результат сложения двух чисел.

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

3. Документация должна быть точной

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

/// <summary>
/// Сообщение в чате. 
/// </summary>
class Message
{
	…
	/// <summary>
	/// Текст сообщения. 
	/// </summary>
	public string Text
	{
		get { return this.text; }
}
}

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

4. Документация должна быть сухой

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

5. В документации не должно быть старого кода

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

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

Если есть сомнения пригодится ли еще этот код, его лучше сохранить в системе контроля версий — именно для этого ее и придумали.

Дальше речь пойдет о том, как писать техническую документацию для программ на C#. Вся работа будет вестись в Visual Studio.

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

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

В C# есть два вида комментариев. Однострочные:

int a = 11 + 12; //Это однострочный комментарий

И многострочные:

/* Начало комментария
Это
Многострочный
Комментарий
Конец комментария */

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

Более продвинутый вариант — использовать XML. Чтобы вставить XML-комментарий, нужно перед названием класса, поля, свойства или метода поставить тройной слеш.

После этого автоматически будет создано два элемента:

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

Практически все инструменты, в том числе и Visual Studio, поддерживают вывод подсказок, которые подгружаются из документации. И теперь, если навести на метод Main () или его аргумент, то можно увидеть, что было написано в комментарии.

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

Еще можно использовать такие XML-элементы, как:

• Returns — возвращаемое значение;
• Value — значение свойства;
• Exception — исключение;
• Remarks — ремарка к основному комментарию.

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

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

Для этого сначала нужно зайти в настройки проекта:

А потом перейти во вкладку Build и поставить галочку XML documentation file:

Теперь вместе с компиляцией программы будет создаваться файл с документацией в формате XML. Его можно преобразовать в HTML с помощью специальных утилит. Microsoft для этого рекомендует использовать DocFX или Sandcastle.

Рассмотрим на примере DocFX. Его можно скачать с помощью NuGet Package Manager в Visual Studio. Для этого нажмите на проект правой кнопкой мыши и выберите пункт Manage NuGet Packages:

Затем перейдите во вкладку Browse и введите в поле поиска название docfx.console, а потом нажмите Install:

После нужно подтвердить установку и согласиться с условиями лицензионного соглашения.

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

namespace ConsoleApp1
{
	/// <summary>
	/// Класс, который представляет пользователя.
	/// </summary>
	public class User
	{
		private string name;

		/// <summary>
		/// Конструктор класса.
		/// </summary>
		/// <param name="name">Имя пользователя.</param>
		public User(string name)
		{
			this.name = name;
		}

		/// <summary>
		/// Меняет имя пользователя.
		/// </summary>
		/// <param name="name">Имя пользователя.</param>
		public void ChangeName(string name)
		{
			this.name = name;
		}

		/// <summary>
		/// Метод для вывода имени пользователя.
		/// </summary>
		/// <returns>Возвращает имя пользователя.</returns>
		public string GetName()
		{
			return this.name;
		}

	}
}

После компиляции проекта с таким классом можно проверить сайт. Его главная страница будет пуста — она нужна для того, чтобы вкратце описать свою программу. Сама же документация находится по адресу api/index.html.

Вот как она выглядит:

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

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

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

• Требования к руководству по эксплуатации
• Важные правила
• Кому может потребоваться руководство по эксплуатации?
• Какими ГОСТ и законами регламентируется порядок оформления документа?
• Каким должно быть содержание руководства по эксплуатации?
• Что может быть дополнительно?
• Как правильно оформить?
• Стиль оформления

Требования к руководству по эксплуатации

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

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

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

Важные правила

Составление РЭ проводится в соответствии с определенными правилами:

• Цель документа – разъяснение. Потребитель с помощью него обеспечивается всей необходимой информацией по использованию продукции;
• Вся представленная информация должна соответствовать остальной технической документации;
• Руководство должно полноценно отражать принципы работы и эксплуатации данного изделия или продукции в целом;
• Вся информация не должна противоречить государственным стандартам и существующим техническим регламентам;
• Язык написания документа должен быть простым, понятным для всех, кто планирует эксплуатировать продукцию.

Кому может потребоваться руководство по эксплуатации?

Документ может быть необходим и быть полезен для:

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

Какими ГОСТ и законами регламентируется порядок оформления документа?

Порядок оформления РЭ определен рядом нормативно-правовых документов и рекомендаций стандартов ЕСКД:

• ГОСТ 2.610-2006 – отражены общая система и правила тех. документов;
• ГОСТ 2.105-95 – отражены правила по тексту технической документации;
• ГОСТ 2.601-95 – указаны требования по оформлению РЭ;
• Также существуют требования, которые регламентируются Таможенным союзом: ТР ТС 016/2011, ТР ТС 010/2011 и другие.
• Для узконаправленной продукции оформление руководства по эксплуатации может еще регламентироваться дополнительными нормативами, например, Правилами безопасности оборудования.

Каким должно быть содержание руководства по эксплуатации?

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

1. Вводная часть;
2. Оглавление;
3. Подробное описание продукта, устройства или механизма;
4. Комплектность;
5. Подробное описание и условия его использования;
6. Монтаж;
7. Сервисное обслуживание, ремонт – указание возможных неполадок и способы их устранения;
8. Применяемые к условию стандарты, требования и нормы безопасности;
9. Гарантии производителя;
10. Правила по хранению и транспортировке;
11. Правила утилизации;
12. Предметный указатель (глоссарий).

Что может быть дополнительно?

Дополнительно РЭ часто содержит:

• FAQ (часто задаваемые вопросы) и ответы на них;
• Ссылки на дополнительную информацию по сфере применения товара;
• Ссылки на обучающее видео;
• Популярные подсказки;
• Краткую аннотацию в начале каждого крупного раздела.

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

Как правильно оформить?

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

Стиль оформления

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

• 
  26.10.2020
• 
  
  Без рубрики

Правила разработки технологических инструкций

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

Кому следует разрабатывать ТИ

Регламент составления таких документов определен межгосударственным стандартом ГОСТ 3.1105-2011, который устанавливает общие правила разработки разных видов технической документации. Этот нормативный документ указывает, в каком случае разрабатывается технологическая инструкция. Согласно этому стандарту, технологические инструкции разрабатываются для:

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

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

Составление ТИ

Написание технологической инструкции ответственному лицу следует производить с учетом указаний, приведенными в разделе 6 ГОСТ 3.1105-2011. Правила разработки ТИ включают следующие принципы:

• производственные процессы нужно описать в соответствии с последовательностью их выполнения;
• документы, имеющие сложную, объемную структуру, стоит разбивать на разделы либо подразделы, нумерация которых осуществляется в соответствии с правилами межгосударственного стандарта ГОСТ 2.105-95;
• если актуаленя вопрос о том, как составить технологическую инструкцию для сложного объекта, то для обеспечения наглядности информации, включаемой в ТИ, разрешается включение рисунков, графических схем, других удобных решений;
• при разработке документации нужно применять формы 5 или 5а, утвержденные стандартом ГОСТ 3.1105-2011.

Формы инструкций с примерами заполнения приведены в приложении Б к интересующему нас межгосударственному стандарту.

Содержание ТИ

В соответствии с требованиями действующего ГОСТ, а также сложившейся практикой правила оформления технологической инструкции предполагают разработку следующих разделов:

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

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

Необходимые документы

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

• информацию о названии и характеристиках товара;
• ассортиментный список;
• коды ТН ВЭД, ОКВЭД 2;
• информацию о компании-производителе;
• сведения о производственных помещениях;
• сведения о сырье, материалах, применяемых на предприятии;
• описание методов изготовления, технологические карты;
• порядок осуществления хранения, приемки, транспортировки изделия.

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

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

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

Зачем и для кого создается документ?

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

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

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

Особенности создания и оформления

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

Руководство может создаваться на подготовительном этапе, как на отдельный продукт, так и на группу однотипных моделей с едиными данными и правилами. Процесс его оформления не отличается от конструкторско-технической документации и регулируется положениями национальных стандартов ГOCТ 2.601-2013 и ГOCТ 2.105-95.

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

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

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

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

Требования к созданию руководства по эксплуатации

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

• ГОСТ 2.610-2013;
• ГОСТ 2.601-2013;
• ТР ТС 010/2011;
• ТР ТС 016/2011.

При производстве устройств узконаправленного стандарта (насосов, арматуры) РЭ составляется с учетом Правил безопасности для промышленного оборудования.

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

Кто разработчик?

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

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

Отправить заявку на разработку руководства по эксплуатации

Вас может заинтересовать

Среди наших клиентов