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

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

Осенью 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.

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

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

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

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

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

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

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

Автор:
John Pratt

Дата создания:
14 Февраль 2021

Дата обновления:
17 Май 2023

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

Определите стиль технического руководства, создав упрощенное руководство по стилю или следуя существующему руководству по стилю, например, Microsoft Style Guide for Technical Manuals. Руководство по стилю поможет в создании скелета руководства и обеспечит последовательность.

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

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

Создайте оглавление и указатель для удобного использования.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Создайте оглавление и индекс для удобства использования.

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

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

Руководство по эксплуатации какого-либо оборудования должно содержать как общую, так и очень подробную информацию об этой машине. Оформляя руководство по эксплуатации, нужно описать:

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

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

Основные принципы оформления содержания руководства по эксплуатации

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

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

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

Также очень важно при оформлении руководства по эксплуатации отдельно прописывать требования к безопасности, преднамеренно выделяя данные разделы или абзацы. Выделить меры безопасности можно предостерегающими словами «Внимание!», «Запрещается!» «Предупреждение!» и т.п.

Если оформляется руководство по эксплуатации на изделие, которое требует повышенной осторожности при использовании, то на титульном листе документа следует сделать соответствующую надпись: например, «ВНИМАНИЕ! ОСОБАЯ ОСТОРОЖНОСТЬ!».

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

Основные принципы технического оформления руководства по эксплуатации

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

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

При оформлении руководства по эксплуатации на бумажном носителе следует использовать листы А4 согласно ГОСТ 2.301. Страницу документа нужно поделить на следующие зоны:

• информационная зона с технической информацией;
• верхний колонтитул – 1-2 строчки;
• нижний колонтитул – 2-3 строчки.

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

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

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

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

Допустим, к вам поступила задача познакомить англо-говорящего пользователя с языком C#. Вы, как исполнитель, решаете начать знакомство со следующего кода:

using System;

class Hello

{

static void Main() {

Console.WriteLine(«Technical writing is an important skill»);

}

}

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

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

Имейте представление о своей аудитории — это верно для всех типов письма. Вы должны знать, кому пишете; используйте язык ваших читателей. Если вы пишете, например, инструкцию по программированию мобильного телефона для широкой публики, вы будете использовать слова, которые поймет большинство людей. Если вы пишете то же руководство для группы разработчиков программного обеспечения для China Mobile Limited, вы будете использовать более технические термины и более сложные функции.

Прежде чем начать писать:

1. Спланируйте, какую информацию вы хотите включить в свой технический документ. Чем больше вы планируете его содержание и структуру, тем быстрее вы добьетесь прогресса.
2. Проведите свое исследование — чтобы написать убедительный документ, вам нужно подкрепить свои выводы приведенной статистикой, мнением экспертов и тематическими исследованиями.
3. Определитесь с вашей структурой. Постарайтесь структурировать ваш документ так, чтобы он хорошо отображал и располагал информацию в логическом порядке.
4. Составьте примерный план того, насколько объемный будет ваш документ, включая количество слов. От 2000 до 4000 слов в документе, который содержит достаточно деталей, чтобы быть полезным предполагаемому пользователю, но при этом его можно будет изучить за один присест.

Напишите вступление — сделайте его максимально коротким. Дайте читателю понять, Кто должен это читать и Почему они должны читать это. Если читатель принадлежит к группе «кто», а ваше «почему» решает его проблему, то вы только что привлекли его внимание.

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

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

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

Далее, я рад предложить вашему вниманию работу со статьей, состоящей из нескольких текстов «How to Create a User Manual» (Приложение 1), где вы вместе со студентами тщательно разберете тему создания качественного руководства пользователя; и сборник дидактических материалов (Приложение 2) содержащий размножаемый раздаточный материал. Выбор методических приемов по выполнению заданий по карточкам остается за преподавателями, в зависимости от ситуации в их группах.

Список литературы и интернет-ресурсов

1. HP Personal Media Drive User’s Guide
2. Dan Gooking. Android Phones & Tablets For Dummies (For Dummies (Computer/Tech)) 1st Edition.
3. http://files.customersaas.com/files/Huawei_P_Smart_(2019)_(Single_SIM)_User_manual.pdf
4. https://www.dummies.com/consumer-electronics/smartphones/droid/how-to-create-a-mobile-hotspot-with-an-android-phone/
5. https://jerz.setonhill.edu/writing/technical-writing/instructions-how-to-write-for-busy-grouchy-people/
6. https://www.wikihow.com/Create-a-User-Manual#tips
7. https://www.dummies.com/

 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, которым будут пользоваться сторонние программисты.

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

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

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

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

Рассмотрим некоторые характеристики стиля поподробнее.

Структура описания

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

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

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

Характер изложения

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

Читателю должно быть комфортно читать текст, поэтому тон текста должен быть доброжелательным, убедительным и объективным.

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

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

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

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

Полнота, достоверность и ясность информации

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

Тексты должны быть краткими, но достаточными для выполнения описанного действия.

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

Под достоверностью понимается актуальность информации.

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

Под ясностью понимается способность точного восприятия информации.

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

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

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

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

Ориентированность текста

Под ориентированностью текста понимается его направленность на определенный круг читателей.

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

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

Терминология

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

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

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

Оформление

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

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

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

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

А какие требования к написанию технических документов предъявляете вы?

Источники:

http://tech-writer.ru/style/special/