17.11.2020 10:24
Marivolina 18 891 Источник
Моим любимым русским техническим писателям посвящается

Работа технического писателя – создавать документы на программные продукты, в основном всевозможные руководства пользователя. Разработка документа – дело непростое. Есть очень много подходов и практик. Например, технические писатели в научно-производственных предприятиях часто пишут по ГОСТам или другим отечественным стандартам. Их цель – точно и верно описать продукт. А technical writers в международных компаниях пишут по style guides (Microsoft Manual of Style, например). В этом случае цель, скорее, донести до пользователя, как продукт работает. Здесь фокус смещен с продукта на читателя.

Мне довелось побыть техническим писателем в разных местах, с разными правилами и политиками. Оглядываясь назад, могу сказать, что даже в НИИ тексты можно переориентировать на конечного пользователя, и документы от этого выиграют. Но в ГОСТах про это не пишут. А style guides, во-первых, на английском, а во-вторых, не афишируются в отечественных конторах типа НПП, КБ, и пр. Поэтому есть явная нехватка информации. Я попробую ее восполнить.

Чем отличаются доки для продуктов Yandex, Google, Microsoft, Apple, от old-school документации, созданной инженерами-конструкторами?

Классический инженер пишет так, чтобы продукт был описан максимально полно и правильно + в соответствии с ГОСТами и принятой терминологией. Причем многие термины и определения в ГОСТах устарели и совсем не красят документы. Но это не проблема для конструкторов — никто и не думает, легко ли пользователю понять текст. А вот доки, сделанные для людей, отличаются: они написаны понятным языком и учитывают интересы пользователя. Вопрос приоритетов.

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

  Конструкторский подход User-oriented
Простота терминов
 Щелчком ЛКМ манипулятора типа «мышь» нажмите на значок папки.
 Щелкните по значку папки.
Квалификация читателя

 Если писать по ГОСТам 20-го века, то нужно объяснять даже такие элементарные операции, как копирование. Потому что раньше это было непонятно.
 Читатель знает, как пользоваться компьютером, и документы не объясняют элементарных вещей.
Подробность
 Щелчком ПКМ нажмите на значок файла на рабочем столе. В открывшемся меню выберите «Копировать». Затем в проводнике откройте папку, в которую вы хотите скопировать файл. Щелчком ПКМ откройте выпадающее меню и выберите «Вставить».
 Скопируйте файл в нужную папку.
Последовательность изложения Последовательное изложение от и до, без прикрас. Пользователь должен прочитать ВСЁ. Потом он должен сам догадаться, что ему нужно, а что нет.
 Пользователь не хочет читать ВСЁ, он хочет перемещаться по темам нелинейно. Поэтому изложение разделено на отдельные самостоятельные статьи, чтобы из них читатель сложил свой собственный сценарий.
Навигация
 Есть только содержание. Все остальное – чтение по порядку, никаких перемещений.
 Всевозможные интерактивные ссылки: на разделы, на серию разделов в одном сценарии, и т.д. Пользователь хочет перемещаться по темам не линейно, а по своему сценарию.
Тип контента
 Все вперемешку: тут тебе и теория, и немного примеров, и процедура, и таблица, чтобы понятнее было.
 Котлеты отдельно, мухи отдельно. Есть топики только процедурные, есть только объясняющие. И между ними, конечно, связь через ссылки.
Хочешь понять и подумать – сначала почитай матчасть. Хочешь сделать – бери и делай по шагам. Это разные топики, потому что и цели у них разные.

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

Спойлер
Легко не будет.