Разработка документации пользователя программного продукта (Ю. В. Кагарлицкий) - главные идеи

Павел Сафин поделился обзором на книгу Юрия Кагарлицкого «Разработка документации пользователя программного продукта. Методика и стиль изложения». Книга будет полезна всем, кто связан с разработкой документации: начинающим техписам, аналитикам, разработчикам  и инженерам поддержки. Заказать книгу можно на сайте издателя.



Collapse )

О точках в ячейках таблиц

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

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

Пикачу относится к электрическим покемонам и может бить обидчиков молниями

Нужно ли ставить точку в конце последнего абзаца?
Collapse )

История профессии технического писателя

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

Collapse )

Об употреблении предлогов

Оригинал взят у techwriter в Об употреблении предлогов


Немало копий было сломано на форумах технических писателей на тему: «Как правильно: нажать кнопку или нажать на кнопку?». Да и с коллегами мы не раз задавались вопросом: употребляется с предлогом или без?
Выдвигалось много обоснований. Например, употребляется «нажать кнопку», т.к. существует английский эквивалент «press the button». «Нажать кнопку» – «калька» с английского словосочетания. Толковые словари утверждают, что оба варианта равноправны: «нажать что-то или на что-то». В итоге, всё сводилось к выводу: надо выбрать один вариант, и, главное, употреблять его последовательно.
При этом для большинства людей, с которыми я обсуждала употребление «нажать (на) кнопку», было ясно и очевидно, что «нажать клавишу» и никак не «нажать на клавишу».
Мне непринципиально, какой вариант используется в технической документации. Интересно разобраться, откуда «ноги растут» у такой вариативности.
Итак.
Collapse )

В чем разница между словами «этот», «данный» и «подобный»?

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

Обратимся к рекомендациям из ГОСТ Р.

Collapse )

Про «функционал» и «функциональность»

 На Тостере как-то давно обсуждали разницу между словами «функционал» и «функциональность». Поделюсь своим мнением на этот счет.

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

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

Collapse )

«Воспользуйтесь переключателем...»

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

Для публикации/снятия с публикации записи в строке с нужной записью воспользуйтесь переключателем «Публикация».

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

Как исправить

1. Исправим отглаголенное «Для публикации/снятия с публикации» на оборот с глаголом: «Чтобы опубликовать или снять с публикации».
2. Заменим абстрактное «воспользуйтесь» на более конкретное «щелкните». Это типовое действие, указанное в Microsoft Style Guide.
3. Переместим «в строке с нужной записью» в конец предложения, чтобы обозначить его связь с переключателем, а не публикацией. Также избавимся от слова «строка» — это лишняя сущность в мире интерфейса. Напишем, что переключатель находится напротив нужной записи.

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

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

«Браузер» или «Веб-браузер»?

Периодически встречаю в документации к гос. проектам слово «веб-браузер». Не надо так.

В англоязычной документации принят термин web browser (веб-обозреватель). Почему не просто browser?

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

В русском языке слово «браузер» не употребляется по отношению к человеку (браузерщик?), так что уточняющее «веб-» здесь не нужно. Напишите просто «браузер» — поймет и чиновник, и бабушка из соседнего подъезда.

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

Техническое задание по ГОСТ 34. Показатели назначения

Показатели назначения — один из самых мутных разделов технического задания. Вот что о нем пишут в ГОСТ 34:

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

Что же писать на самом деле — не понятно. Как правило всё сводится к одному из трёх вариантов:


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

  2. Писать конкретные измеримо-достижимые показатели, которые потом можно проверить на приемосдаточных испытаниях.

  3. Ограничиться общими фразами.

Collapse )

Координатно-указательное устройство

Иногда в документации для государственных заказчиков встречаются вот такие «приветы из прошлого»:

Технические характеристики персональных компьютеров пользователей:
— Координатно-указательное устройство – манипулятор типа «мышь»;
— Клавиатура – не менее 104 клавиш (русифицированная).

Будто попал в СССР на курсы обучения основам работы с ЭВМ.

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

Если что-то очевидно даже ребенку — не пишите.