Клуб технических писателей

Клуб технических писателей

"Шедевры" из технической документации

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

    • Номер одного из пунктов в документе технического характера

      2.1.3.1.1.16.1.3.2.1



    • Из руководства разработчика

      Порядок слоев объектов отображения в списке отображения определяет порядок слоев отображения независимо от положения объектов по соответствующим осям.



    • 4 причастных оборота в одном предложении

      Введите авторизационный код, отправленный в SMS на номер, оканчивающийся на ХХХХ, действующий в течение 24 часов, или перейдите по вложенной в SMS ссылке.



А с какими "шедеврами" сталкивались вы в своей практике? Что вы делаете, чтобы избежать таких шедевров в вашей документации / документации вашей компании?

20 комментариев
Авторизуйтесь, чтобы оставить комментарий
Орлова Наталья
28 января 2016, 03:14

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

 

Эту фразу я бы нарезала помельче.
Введите код авторизации или перейдите по ссылке из SMS. SMS была отпарвлена на номер, заканчивающийся цифрами ХХХХ. Код действйет в течение 24 часов.

 

Чтобы не плодить шедевров из причастных оборотов и цепочек существительных - писать в сознании, а не на автопилоте. ;-)

 

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

Кристина
28 января 2016, 03:14
Во втором примере причастных оборота только три, уж извините.

А как же "по вложенной в SMS ссылке"? 

Эту фразу я бы нарезала помельче.

Да, конечно, здравая мысль. 

Чтобы не плодить шедевров из причастных оборотов и цепочек существительных - писать в сознании, а не на автопилоте.

А если коллега наплодит такое? Как отслеживаете? Как договариваетесь с ним(ней), чтобы он(а) такого больше не делал(а)?

bryston
28 января 2016, 03:14

Кристина, спасибо за тему!

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

 

Например, Раздел 1.1.,  подраздел 1.1.1.1, глава 1.1.1 и т. д. 

Но больше всего подобные "вещи" попадаются в листе регистрации изменений:

В главе 5.5.5.5. «Импорт отфильтрованных данных» были обновлены снимки экрана.

Выход только один: заранее оговорить не только структуру документа но и его составляющие (разделы, подразделы, пункты, подпункты)...

Кристина
28 января 2016, 03:14
Какую глубину вложенности нумерации вы считаете допустимой? По моим собственным ощущениям (читателя), максимум трёхуровневая нумерация воспринимается нормально.
bryston
28 января 2016, 03:14

Печатные руководства — три: 

глава 1.

параграф 1.1.

раздел 1.1.1.

 Электронные — четыре: 

раздел 1.

подраздел 1.1.

пункт 1.1.1.

подпункт 1.1.1.1.

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

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

Для того чтобы распечатать документ:

- Выделите нужную запись.

- Нажмите на кнопку .

- В открывшемся окне нажмите на кнопку .

Запуск системы осуществляется одним из следующих способов:

1. Нажмите на кнопку на панели задач Windows и выберите пункт меню .

2. Щелкните левой клавишей мыши по кнопке на панели задач.

3. Щелкните дважды левой клавишей мыши по ярлыку .

Порой — без маркеров вообще:

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

 

dzotty
28 января 2016, 03:14

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

bryston
28 января 2016, 03:14

Ваш вариант подходит только для электронной документации...

Если описываемое Вами содержит, например, 10 шагов, то в одно предложение все это уместить сложновато...

dzotty
28 января 2016, 03:14

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

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

bryston
28 января 2016, 03:14

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

А рисунки вставляют после каждого шага, например: 

1. Нажмите на кнопку... (рис. 1)

рис. 1

2. Установите флажок... (рис. 2)

рис. 2

3. Установите переключатель в положение... (рис. 3)

рис. 3

и т. д.

Для электронного документа делали даже для каждого шага всплывающие подсказки и мини-анимации :)

Кристина
28 января 2016, 03:14
Ну, случай с маркированными/нумерованными списками это отдельная история, речь же о нумерации разделов, глав, параграфов и т.п.
bryston
28 января 2016, 03:14

Если "шедевры" — то все "шедевры" :)

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

dzotty
28 января 2016, 03:14

Я делаю три уровня нумерованных разделов, а дальше ненумерованные подзаголовки.

Кристина
28 января 2016, 03:14
+1
Придерживаюсь такой же тактики.
Ирина С.
28 января 2016, 03:14

А эти ненумерованные уже считаются все на одном уровне или есть иерархия?

А в содержание они попадают или нет?

А в электронной документации эти разделы являются отдельными топиками или все вместе составляют содержимое раздела Х.Х.Х?

Прошу прощения за ворох вопросов — больная тема...

Кристина
28 января 2016, 03:14
1 - все на одном уровне. Встречаю часто, что делают иерархию, например разным размером шрифта или разным цветом, но читателю уже все равно будет - в такой иерархии не разберешься и не запомнишь, что к чему относится.
2 - могут попадать, а могут не попадать, зависит от конкретного случая.
3 - не очень поняла, что имеется в виду.
Ирина С.
28 января 2016, 03:14

Спасибо за ответ, Кристина.

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

Кристина
28 января 2016, 03:14
Поняла. Это зависит от объема ненумерованного раздела. Простынка на много экранов - нехорошо.
dzotty
28 января 2016, 03:14

 

"Шедевры" бывают очень часто. Есть люди, которые технически очень хорошо знают объект документирования (поддержка), но очень вольно обращаются с русским языком. Вычитываем, правим, корректируем, объясняем авторам основные косяки.

 

Алексей
28 января 2016, 03:14

2.1.3.1.1.16.1.3.2.1 - круче этого я ещё ничего не видел. Это надо быть богом...

Кристина
28 января 2016, 03:14

О, да :)