Работа технического писателя создавать документы на программные продукты, в основном всевозможные руководства пользователя. Разработка документа дело непростое. Есть очень много подходов и практик. Например, технические писатели в научно-производственных предприятиях часто пишут по ГОСТам или другим отечественным стандартам. Их цель точно и верно описать продукт. А technical writers в международных компаниях пишут по style guides (Microsoft Manual of Style, например). В этом случае цель, скорее, донести до пользователя, как продукт работает. Здесь фокус смещен с продукта на читателя.
Мне довелось побыть техническим писателем в разных местах, с разными правилами и политиками. Оглядываясь назад, могу сказать, что даже в НИИ тексты можно переориентировать на конечного пользователя, и документы от этого выиграют. Но в ГОСТах про это не пишут. А style guides, во-первых, на английском, а во-вторых, не афишируются в отечественных конторах типа НПП, КБ, и пр. Поэтому есть явная нехватка информации. Я попробую ее восполнить.
Чем отличаются доки для продуктов Yandex, Google, Microsoft, Apple, от old-school документации, созданной инженерами-конструкторами?
Классический инженер пишет так, чтобы продукт был описан максимально полно и правильно + в соответствии с ГОСТами и принятой терминологией. Причем многие термины и определения в ГОСТах устарели и совсем не красят документы. Но это не проблема для конструкторов никто и не думает, легко ли пользователю понять текст. А вот доки, сделанные для людей, отличаются: они написаны понятным языком и учитывают интересы пользователя. Вопрос приоритетов.
Эти приоритеты и цели автора очень влияют на то, какие получаются документы. Давайте на примерах посмотрим, как это выглядит в жизни:
| Конструкторский подход | User-oriented |
|
|---|---|---|
| Простота терминов |
Щелчком ЛКМ манипулятора типа мышь нажмите на значок
папки. |
Щелкните по значку папки. |
| Квалификация читателя |
Если писать по ГОСТам 20-го века, то нужно объяснять даже такие
элементарные операции, как копирование. Потому что раньше это было
непонятно. |
Читатель знает, как пользоваться компьютером, и документы не объясняют элементарных вещей. |
| Подробность |
Щелчком ПКМ нажмите на значок файла на рабочем столе. В
открывшемся меню выберите Копировать. Затем в проводнике откройте
папку, в которую вы хотите скопировать файл. Щелчком ПКМ откройте
выпадающее меню и выберите Вставить. |
Скопируйте файл в нужную папку. |
| Последовательность изложения | Последовательное изложение от и до, без прикрас. Пользователь
должен прочитать ВСЁ. Потом он должен сам догадаться, что ему
нужно, а что нет. |
Пользователь не хочет читать ВСЁ, он хочет перемещаться по
темам нелинейно. Поэтому изложение разделено на отдельные
самостоятельные статьи, чтобы из них читатель сложил свой
собственный сценарий. |
| Навигация |
Есть только содержание. Все остальное чтение по порядку,
никаких перемещений. |
Всевозможные интерактивные ссылки: на разделы, на серию
разделов в одном сценарии, и т.д. Пользователь хочет перемещаться
по темам не линейно, а по своему сценарию. |
| Тип контента |
Все вперемешку: тут тебе и теория, и немного примеров, и
процедура, и таблица, чтобы понятнее было. |
Котлеты отдельно, мухи отдельно. Есть топики только
процедурные, есть только объясняющие. И между ними, конечно, связь
через ссылки. Хочешь понять и подумать сначала почитай матчасть. Хочешь сделать бери и делай по шагам. Это разные топики, потому что и цели у них разные. |
Такое бывает, что ты смотришь на документы, а они уже морально устарели. Как будто читаешь инструкцию к трактору 1950-х годов. Нужно как-то сделать их более актуальными, но это кажется невозможным. На самом деле, возможно всё. В следующих статьях я разберу пошагово, как именно от огромного устаревшего комплекта документации перейти к легким, понятным, современным докам. Каждый из пунктов таблицы мы разберем в отдельной статье.
Спойлер
Легко не будет.
