Секреты написания хорошей документации
Перевод статьи «How to Write Good Documentation».
В этой статье я расскажу о трех шагах, которые помогут вам не забыть, как работает ваш проект.
Вероятно, вам случалось оставить проект сделанным наполовину, а потом уйти на несколько дней в отпуск. Теперь вы узнаете, что нужно делать, чтобы потом без проблем вернуться к работе.
В командах, где я выступаю в роли тимлида, мы стараемся постоянно все документировать. Документация живет своей жизнью параллельно с кодом, она — равнозначный игрок.
Благодаря этому никому не приходится строить догадки, как работает та или иная вещь. Не приходится проводить длительные совещания для обмена знаниями. Хорошая документация экономит нам много времени и избавляет от нудной рутины.
Вопреки распространенному мнению, самая ценная документация пишется не для других людей. Как я написала в одном твите,
«Секрет хорошей документации в том, что ее надо писать параллельно с написанием кода. Ваша первая аудитория — вы сами. Объясните самому себе, что вы делаете. В будущем вы будете благодарны себе за это».
Итак, переходим к конкретике. Вот три шага, которые нужно сделать для написания хорошей документации.
1. Начните со скрупулезного ведения заметок
Воплощая свои идеи в код, обязательно ведите записи. Это поможет вам не забыть важные детали. Хотя впоследствии вы еще распишете все подробно, короткие пометки способны вместить достаточно деталей и вместе с тем не будут сильно отвлекать вас от написания кода.
Пока пишете код, держите открытым файл, где ведете записи. Вносите в него такие вещи как примененные команды, принятые решения, использованные ресурсы. Вы можете записывать:
На этом этапе не обязательно даже писать полными предложениями. Просто следите за тем, чтобы точно передавать контекст, прикладывать соответствующие отрывки кода и полезные URL. Также будет полезным включить опцию автосохранения для этого файла.
2. Объясните свои решения более подробно
Идеальное время для написания пространных объяснений — перерыв после написания кода и перед уходом на обед или переключением на другую задачу.
Чтобы все хорошо и подробно объяснить себе будущему, вам нужны свежие воспоминания о контексте, идеях и решениях.
Вернитесь к своим коротким заметкам и начните расширять их, придерживаясь разговорного стиля. Побудьте своей резиновой уточкой. Объясните, что вы делаете, как будто вы учите кого-то другого. На этом этапе вы можете раскрыть такие темы как:
Не слишком вдавайтесь в детали, сосредоточьтесь на главном. То, что эти объяснения более многословные, чем ваши короткие заметки, еще не значит, что надо писать так, будто вам платят за каждое слово. Просто используйте полные предложения и пишите так, будто объясняете проект коллеге. В конце концов, вы же для себя пишете.
3. Не забудьте упомянуть о предварительных знаниях
Этот шаг лучше делать после полноценного обеденного перерыва или даже на следующий день (но два дня — это уже пожалуй перебор). Перечитайте написанную документацию и заполните все пробелы, которые стали заметны после некоторого дистанцирования от проекта.
Сделайте дополнительные усилия и напишите, какие предварительные знания и навыки нужны для работы над этим проектом (или хотя бы ссылок набросайте). Особенно это касается случаев, когда вы часто использовали разные языки или инструменты. Даже такая мелочь, как вставка ссылки на документацию используемого API, может в дальнейшем сэкономить часы на поиски.
Напишите или прикрепите ссылки на все нужные README, шаги установки, релевантные запросы в поддержку. Для часто осуществляемых действий в командной строке можно использовать самодокументирующийся Makefile. Таким образом вам не придется открывать man для повторяющихся задач при каждом возвращении к проекту.
Спустя некоторое (даже довольно короткое!) время легко забыть какие-то детали, связанные с проектом, но не являющиеся его непосредственной частью. Записывайте все, что сочтете полезным.
Документируйте всё!
В следующий раз, когда поймаете себя на мысли «Я это точно запомню, нет нужды записывать», вспомните какую-нибудь картинку типа фейспалм.jpg.
Проекты создания программ представляют собой намного больше, чем просто код. Чтобы в будущем сразу успешно начать работать с любым своим проектом, документируйте всё! Будь то установленная вами процедура, инфраструктура как код или мимолетная идея на будущее — записывайте! Когда-нибудь вы поблагодарите себя за это.
Пишем техническую документацию: руководство для непрофессионала
Осенью 2016 года нам с коллегой поручили улучшить документацию и контент в моей бывшей компании. Мы потратили год на все виды документации: справочник по API, руководства, учебные пособия, сообщения в блогах. До этого я 5 лет писала доки, но официально не обучалась этому. Но и неопытной меня нельзя назвать: кроме документирования API для проектов и стартапа, я ещё преподавала Python Flask на семинарах во время учёбы на последних курсах в университете. Но сейчас выпала возможность сосредоточиться только на любимом деле: помогать специалистам всех уровней через техническую документацию.
В этом году я многому научилась в сообществе Write The Docs, у других провайдеров API, а также методом проб и ошибок. В прошлом году я поделилась опытом в докладе «Что мне хотелось бы знать о написании документации» на конференции API Strategy and Practice в Портленде. Эта статья — обзор полученных знаний.
Как люди на самом деле читают документацию?
«Нация содрогается от большого фрагмента слитного текста», фото The Onion
Знаете это чувство, как на картинке? Так бывает. Может и не физически, но, скорее всего, люди содрогаются умственно. Меня постоянно мучала мысль, что люди не будут читать мои тексты, если я не оформлю их легко усваиваемым способом. Чёрт возьми, такое может произойти даже с этой статьёй.
В исследовании направления взгляда Neilson Norman Group в 2006 году 232 пользователя просмотрели тысячи веб-страниц. Оказалось, что пользователи обычно смотрят на страницы по F-шаблону:
Теплокарты Nielsen Norman Group
Исследование обнаружило некоторые альтернативные паттерны сканирования, такие как шаблон слоёного торта, пятнистая карта, шаблон разметки, шаблон обхода и целеустремлённый шаблон. Настоятельно рекомендую ознакомиться с докладом.
Важно отметить, что F-шаблон мешает пользователям, но хорошее позиционирование контента помогает предотвратить F-сканирование.
Каковы конкретные последствия для документации?
Так как структурировать контент на странице?
Кроме того, у абзацев есть своя специфика. Подобно слитному тексту The Onion, когда вы читаете много абзацев, можно пропустить суть. Тогда зачем использовать их так часто? Давайте проведём эксперимент из документации Keen IO:
Быстро прочитайте это:
У наборов событий может быть практически любое название, но есть несколько правил: в названии должно быть не более 64 знаков. Оно должно содержать только символы ASCII. Оно не может быть значением null.
Теперь быстро прочитайте это:
У наборов событий может быть практически любое название, но есть несколько правил:
Позже мы подробнее обсудим вёрстку документации и навигацию по ней.
Примеры кода
Что такое документация API без кода, верно? Примеры кода есть во многих наших документах, и пользователи действительно их читают. Но проблема в том, что они не всегда обращают внимание на окружающий текст.
Контекст в примере кода важен для успеха разработчика. Разработчики любят быстро копировать и вставлять. Вот пример с Keen IO API:
Разработчик быстро копирует и вставляет этот код. И…
Пользователь всё починил и запустил ещё раз… Угадайте?! Ещё одна ошибка! your_project_id и your_write_key отсутствуют.
Всё это можно было бы сделать более очевидным.
Вот пример из документации Twilio, которая предоставляет хороший контекст для конечного пользователя:
Скриншот из документации библиотеки Twilio Node Helper
Это сразу проясняет, как установить библиотеку, внедрить её в свой код и что нужно заменить в образце кода перед его запуском.
Копипаст багов
Поскольку у нас в документации много примеров кода, успешный копипаст — довольно важное свойство. Вот два примера того, где это не соблюдается:
Кажется довольно безобидным, верно? Подумайте ещё раз, что происходит, когда вы копируете и вставляете это в командную строку? Вы, скорее всего, получите:
Более свежий пример: вы проверяли, насколько легко выделить код, который пользователь хочет скопировать?
Келси Хайтауэр изо всех сил пытался скопировать образец кода из StackOverflow на презентации Google Cloud Next.
In a LIVE DEMO, watch @kelseyhightower build a weather application from zero. Starting from the database up to the end point: https://t.co/XAKsOYSHZq pic.twitter.com/1iuHGlVRnR
«Хорошие программисты копируют, великие программисты вставляют»
Он сделал это намеренно? Мы никогда этого не узнаем. Тем не менее, это иллюстрация, как программисты пытаются выделить большие блоки текста на некоторых сайтах документации. Убедитесь, что пользовательский интерфейс сайта позволяет легко копировать большие блоки. Можно даже разбить эти блоки, чтобы объяснить фрагменты по отдельности. Так они станут доступнее для копирования и понимания.
«Вот и всё!»
«Вот и всё!» Фраза кажется довольно безобидной вне контекста, но представьте, как воспринимаются определённые слова вроде «легко», «просто», «тривиально» и «несложно», когда у вас проблемы — не здорово! Когда человек застрял, пытаясь заставить API работать, такая фраза подвергает сомнению его интеллект и заставляет задать вопрос: «Значит, я глупый?» Это деморализует.
Чрезмерное упрощение
Упрощение встречается повсеместно. Оно наиболее распространено среди новичков в написании документации. Зачастую авторы документации — одновременно и разработчики системы, поэтому некоторые вещи им кажутся «лёгкими». Но ведь они разработали эту функцию, написали для неё код, проверили много, много раз, а потом написали документацию. Когда вы делаете что-то десятки раз, то ясное дело, что это будет «легко» для вас. Но как насчёт того, кто никогда раньше не видел UI или функцию?
Сопереживание
Выбор слов действительно имеет значение. Эмпатия — это способность понимать и разделять чувства других. Когда мы проявляем эмпатию, то помогаем не только новичкам, но и более продвинутым пользователям. Это помогает увеличить потенциальное количество пользователей, вариантов использования, клиентов и даже доход компании.
Но когда документацию пишет эксперт-разработчик проекта, проявить эмпатию сложнее. Вот несколько полезных советов, которые помогли мне в прошлом:
Сообщения об ошибках как вид документации
Обычно пользователи чаще видят сообщения об ошибках, чем документацию. Как говорит Кейт Восс, «сообщения об ошибках на самом деле представляют собой возможность». Я считаю, что многие разработчики документации упускают эту возможность. Здесь есть место для обучения, установления доверительных отношений и ожиданий пользователей. Прежде всего, вы поможете людям помочь самим себе.
Кейт на сайте Write The Docs рассказывает много полезного о написании сообщений об ошибках. Многое я узнала во время прошлой работы над сообщениями об ошибках API, а также будучи на другой стороне баррикад, получая сообщения об ошибках других API в качестве разработчика.
Кейт говорит, что хорошие сообщения об ошибках построены на трёх принципах:
Скромность
Сразу нужно извиниться, даже если это не ваша вина. Это я практикую также в службе поддержки.
Извините, не удалось подключиться к ___. Пожалуйста, проверьте сетевые настройки, подключитесь к доступной сети и повторите попытку.
Гуманность
Используйте понятные человеку термины, избегайте фраз типа «исключение выброшено целевым объектом вызова». При написании кода, для которого вызывается много сообщений об ошибках, легко сбиться с понятной лексики.
Пример (ошибка кода состояния 401 у Twilio):
Полезность
Если вы запомните что-то из этих советов, запомните о полезности. Поделитесь с пользователем информацией, как устранить проблему.
Извините, изображение, которое вы пытались загрузить, слишком большое. Попробуйте снова с изображения меньше, чем 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 по-китайски означает «больной».
Почти 25% разработчиков читают и пишут по-английски не «очень хорошо». При общении в проекте используйте понятный и доступный язык для людей из неанглоязычных стран.
Вы это учитываете, когда используете американизмы и идиомы в документации? Многие из них могут быть непонятны для пользователей.
Подсказка: я твёрдо верю, что один из величайших «трюков» для решения этих проблем — разнообразие команды, работающей над документацией.
Есть ещё случаи, когда мы признаём ошибку, но не можем или не хотим её исправлять, потому что мы…
Нельзя бояться рефакторинга и переписывания, когда речь идёт о документации. Как же её улучшить, если не соглашаться с тем, что изначально сделан не лучший выбор?
Как правильно подобрать слова?
Для начала рекомендую задать вопрос: какие слова используют ваши пользователи? В разных программистских кругах в ходу разные термины, не пытайтесь использовать другие. Это полезно не только для читателей, но также для поиска и SEO.
В конце концов, всё неизбежно сводится к субъективной оценке. Однако есть несколько принципов, которые стоит учесть. Рути говорит, что плохие названия — это те, что могут:
Подбирать верные слова трудно. Волшебной формулы не существует. Все пользователи отличаются, как и варианты использования продукта; что работает для одних, может не работать для других. Если бы это было легко, у всех была бы намного лучшая документация. Как говорит Рути разработчикам: «Написание программ — это упражнение в придумывании названий. Смиритесь с этим». И если вы пишете документацию для чужой программы, «сообщите разработчику, если его названия не попадают в цель».
7 правил написания технической документации мирового класса
Введение
Написание технического документа — трудное дело. Чтение плохо написанного технического документа является более трудным и, вероятно, более болезненным делом, чем его написание. Требуется большая работа, чтобы создать ясное, точное, интересное техническое описание. Поэтому, чтобы сделать жизнь хоть немного проще для всех участвующих сторон, я хотел бы поделиться с вами семью правилами, которым я следую, создавая техническую документацию.
Эти правила — не моё собственное изобретение. Скорее, я просто сформулировал их из того опыта, который появился благодаря общению со многими талантливыми техническими и литературными редакторами за более чем десять лет работы. Всё, что я понял в этом деле, сформировалось потому, что другие показали мне путь. У меня не находится достаточно слов, чтобы выразить им в полной мере мою благодарность.
Надеюсь, после прочтения этой статьи в вашем арсенале появятся некоторые новые инструменты, которые помогут вам создавать технические документы на новом уровне качества: более ясные, более привлекательные, менее путанные и намного более интересные для чтения. Также я добавил — без всяких каких-либо дополнительных требований к вам, как потребителю, бонус в конце статьи: описание процесса, используемого мною для создания технического описания.
1. Скука убивает
Это правило является, по-видимому, самым трудным для формализации и самым важным по необходимости соблюдения. В современном мире интернета действует много сил, борющихся за внимание вашего читателя. Скучное стандартное описание работать не будет. При любых обстоятельствах ваш читатель желает, чтобы было увлекательно и информативно. Поэтому, если ваш текст неясный или неинтересный, то читатель просто щёлкнет пресловутую кнопку «Далее» и перейдёт на другую веб-страницу или на другую ТВ-программу или на свою страницу в Фейсбуке.
Самый простой путь, который я нашёл для пробуждения интереса у читателя, состоит в том, чтобы интересно было мне самому. Я всегда прилагаю значительные усилия, чтобы написать такую статью, которую сам хотел бы прочитать. Я стремлюсь получать удовольствие от того, что пишу. Если мне скучно, то заскучает и читатель. Если я запутался, то запутается и читатель. Если меня не волнует рассматриваемая тема, то читатель, тем более, не взволнуется. Всё очень просто!
Мне нравится юмор, поэтому я стараюсь сделать мои литературные технические «творения» забавными, но, конечно, без ущерба для ясности. Пытаюсь разговаривать с читателем, а не поучать его. Пишу о делах, которые, действительно, имеют значение для меня. Широко использую иллюстрации, чтобы предотвратить неясность для читателя.
И снова, всегда стараюсь сделать процесс чтения увлекательным. Я всегда помню, что пишу в конкурентной среде. Имеется множество контента, стремящегося привлечь внимание читателей. Таким образом, мой совет по правилу № 1: если ваши тексты будут интересны вам, то они будет интересными и для читателя.
2. Прежде чем начать, выясните точно для себя, какие действия вы ожидаете от читателя, осилившего ваш труд
Техническая документация полностью завязана на последующее поведение читателя. Читатель затрачивает своё время на чтение вашего творения, потому что он или она имеет намерение сделать что-то после завершения процесса чтения. Этим «что-то» может быть выпечка печенья с кусочками шоколада, остановка ядерного реактора или разработка кластера Hadoop. Важно помнить, что читатель использует ваше описание как средство для выполнения другого процесса. Ваш труд является неким проводником к дальнейшему вполне определённому поведению.
Поэтому чрезвычайно полезно для вас чётко определиться, какие действия вы ожидаете от читателя после завершения процесса чтения. Изложите ваше намерение с самого начала. Не оставляйте читателя гадать. Ваше заявление может быть простым и очевидным, как, например: «после прочтения данной статьи вы сможете [впишите свой вариант]». Если вы определились с действиями, ожидаемыми от читателя после прочтения, то процесс написания будет для вас легче с самого начала.
3. Пишите в соответствии с правильно сформированной структурой
Хорошо сформированная структура является тем остовом, вокруг которого растёт ваш документ. Подготовка технического документа без использования некоторой структуры равносильна попытке ориентироваться в метро Нью-Йорка (469 станций!) без схемы. Вы можете оказаться где угодно, но это «где угодно» может оказаться совсем не тем местом, куда вы предполагали попасть.
Написание технической документации в соответствии со структурой не означает увеличение объёма работы. Наоборот, нагрузка уменьшается. Работая со структурой, вы знаете, откуда вы выходите и куда собираетесь прийти.
Имеются два правила структурирования, которые я всегда использую:
1. Раздел подуровня требует наличия, как минимум, одной позиции.
2. На каждом уровне структуры должно быть, как минимум, два предложения.
Хотелось бы уточнить. Листинг 1 внизу является примером структуры, которая нарушает первое правило: раздел подуровня требует наличия, как минимум, одной позиции.
Листинг 1: неправильно сформированная структура
1. Приготовление апельсиново-клюквенно-мандаринового шипучего напитка
1.1. Шаги, требуемые для приготовления шипучего напитка
1.1.1. Подготовка ингредиентов
1.1.2. Смешивание ингредиентов шипучего напитка
1.1.3. Подача шипучего напитка
Обратите внимание, что в листинге 1 уровень 1 имеет одиночный подуровень: «1.1. Шаги, требуемые для приготовления шипучего напитка«. Такая структура является нарушением первого правила. Чтобы подуровень был правильно сформирован, в разделе должна быть, как минимум, ещё одна позиция. Другими словами, это значит, что на любом данном уровне должно быть, как минимум, два подуровня.
Посмотрите листинг 2 внизу. Обратите внимание, что у уровня 1 теперь имеются три подуровня, из которых раздел «Смешивание ингредиентов шипучего напитка» содержит позиции. Одиночный уровень «Шаги, требуемые для приготовления шипучего напитка» удалён.
Может возникнуть вопрос: «Где раздел Шаги, требуемые для приготовления шипучего напитка». Видно, что этот раздел теперь не является позицией структуры, а перешёл в контент исходного раздела, как показано в листинге 2 внизу.
Листинг 2: правильно сформированная структура, нарушающая правило двух предложений
1. Приготовление апельсиново-клюквенно-мандаринового шипучего напитка
Раздел внизу описывает процесс, который надо соблюсти для приготовления апельсиново-клюквенно-мандаринового шипучего напитка.
1.1. Подготовка ингредиентов
1.2. Смешивание ингредиентов шипучего напитка
1.3. Подача шипучего напитка
Обратите внимание, что, хотя листинг 2 демонстрирует структуру с правильно сформированным подуровнем, в контенте раздела уровня 1 имеется только одно предложение. Присутствие одного единственного предложения в контенте раздела структуры нарушает второе правило структурирования — «На каждом уровне структуры должно быть, как минимум, два предложения«.
Листинг 3 показывает тот же текст, но изменённый с целью обеспечить выполнение правила двух предложений.
Листинг 3: правильно сформированная структура, выполняющая правило двух предложений
1. Приготовление шипучего апельсиново-клюквенно-мандаринового напитка
Апельсиново-клюквенно-мандариновый шипучий напиток может доставить большое удовольствие в жаркий летний день. Напиток состоит из природных компонентов без искусственных ароматизаторов. Апельсиново-клюквенно-мандариновый шипучий напиток не только вкусный, но и чрезвычайно полезный!
Разделы внизу описывают процесс, который надо соблюсти для приготовления апельсиново-клюквенно-мандаринового шипучего напитка.
1.1. Подготовка ингредиентов
1.2. Смешивание ингредиентов шипучего напитка
1.3. Подача шипучего напитка
Почему я так беспокоюсь о правильной структуре и о, по крайней мере, двух предложениях на каждом уровне? Во-первых, соблюдение правила подуровня побуждает меня быть предельно чётким в логической сегментации моего труда. Следование правилу подуровня способствует также тому, что мой текст соединяет мои идеи с общей линией, которая имеет смысл и легко прослеживается.
Во-вторых, правило двух предложений требует от меня написать текст, который является привлекательным, подробным и целесообразным. При записи в «одно предложение» нередко теряются подробности. И, если не рассматривать афоризмы, текст в «одно предложение» — не самое интересное чтение.
4. Избегайте неоднозначных местоимений
Неоднозначное использование местоимений является, вероятно, самой типичной причиной путаницы в практике подготовки технических описаний.
Рассмотрим абзац в листинге 4.
Листинг 4: абзац с неоднозначными местоимениями
Трафальгаборы являются базовой компонентой фрейма Вибитатов. Эта статья показывает, чем они являются и как их использовать.
Данный абзац выглядит, возможно, несколько комично, но он иллюстрирует некоторые важные точки. Во-первых, абзац пытается поставить вас на место, которое занимает читатель. Читатель желает понять, что происходит, но он незнаком с используемыми терминами. А поскольку термины непонятны, то читатель ощущает себя некомпетентным и потому уязвимым. Читателю нужна новая информация — он или она желает стать умнее. Но читатель также немного беспокоится. Допущение собственной некомпетентности, даже перед самим собой, даже на подсознательном уровне — может быть ему неприятно. Читатель болезненно чувствителен к пониманию представляемого материала. Понятия и слова, которые вы, лицо пишущее, считаете само собой разумеющимися, могут быть полностью чуждыми читателю. Одно плохо объяснённое понятие или одно слово, использованное без надлежащего разъяснения, могут подтолкнуть читателя прекратить чтение.
Применительно к абзацу вверху я не удивлюсь, если вы спросите: «Что это за штука „Трафальгабор“? А что такое „Вибитата“? О чём, вообще, этот абзац? О том, как использовать Трафальгаборы? Или о том, как использовать Вибитаты? Или о том, как использовать и те, и другие? Бред какой-то. Вернусь я лучше на свою страницу в Фейсбуке».
Если читатель при чтении вашего описания вынужден тратить время на выяснение, что же вы пытаетесь ему сообщить, то мало того, что информативный поток будет нарушен, но и читатель, скорее всего, будет запутан. Как только вы привели читателя в замешательство, вы его потеряли. Всё другое в мире, направленное на привлечение внимания вашего читателя, становится для него более притягательным, чем ваше творение. Щелчок по кнопке «Далее» — и ваша работа остаётся непрочитанной.
В листинге 4 замешательство порождается неоднозначным использованием местоимения «они» во втором предложении. К чему относится здесь «они» — к Трафальгаборам, Вибитатам или к обоим? Помните, что читатель ничего не знает, что такое Трафальгаборы или Вибитаты. (См. рис. 1 внизу.)
Рис. 1. Использование неоднозначных местоимений запутывает техническое описание
Решение проблемы простое. Посмотрите листинг 5 внизу. Неоднозначное местоимение удалено. Ясность восстановлена.
Листинг 5: устранение неоднозначных местоимений
Трафальгаборы являются базовой компонентой фрейма Вибитатов. Эта статья рассказывает, что такое Трафальгаборы и как их использовать.
Осторожно! Неоднозначное использование местоимений ведёт к техническому описанию, приводящему в замешательство.
5. Ясность = иллюстрации + слова
Посмотрите на фотографию внизу. Скажите, если сможете, о чём это фото?
Я не удивлюсь, если вы будете немного растеряны. Эта фотография, действительно, озадачивает. Вы знаете все отдельные компоненты, но вам неясно, что они все вместе значат. Такова природа любой иллюстрации. Картинке без слов не хватает контекста.
При обращении к иллюстрациям читателям требуется контекст, чтобы внести ясность. Недопустимо, чтобы читатель напрасно тратил время или усилия, пытаясь выяснить, о чём же рассматриваемая графика. Самым лёгким путём устранить неясность с иллюстрациями является обеспечить их надписями.
Посмотрите на рис. 2 внизу. Он представляет собой то же самое фото. Но здесь уже нет вопроса, о чём оно.
Рис. 2. Инструменты и ингредиенты, требуемые для приготовления апельсиново-клюквенно-мандаринового шипучего напитка
Применительно к техническим описаниям я считаю полезным все иллюстрации снабжать пронумерованными описательными надписями.
Не помещайте надписи, содержащие только цифры. Используйте в надписи, как цифры, так и описательный комментарий. Также не допускайте появления изолированных иллюстраций. Изолированной иллюстрацией считается такая, которая расположена в техническом описании, но ссылка на которую в тексте отсутствует.
Вставляя иллюстрацию в ваше описание, следите за тем, чтобы сослаться на неё в тексте указанием её номера и таких слов как «выше», «вверху», «ниже», «внизу». Недопустимо вынуждать читателя при чтении вашей работы тратить время на привязку иллюстрации к тексту или на её поиск в описании. Если вы добавляете в текст, скажем, «Рис. 4», то убедитесь, что где-то в тексте сказано что-то вроде «см. рис. 4 внизу».
Примечание: глаз привлекают изображения
Десять лет назад я работал в группе, которая писала пользовательское руководство (под типографское издание) для очень, очень большого изготовителя компьютеров. Все руководства подвергались формальному количественному исследованию на удобство пользования. Тогда от специалистов по взаимодействию с пользователем я узнал, что, когда человек читает руководство, глаз его идёт сначала к изображениям. Лишь затем читатель смотрит на текст вокруг этого изображения. Поэтому авторы того руководства пытались обеспечить, чтобы на каждой его странице была хотя бы одна картинка.
6. Когда имеете дело с понятиями, концепциями и т.п., используйте логическую иллюстрацию и пример, логическую иллюстрацию и пример
Понятия трудны для понимания — и это то, почему они называются «понятиями». Поэтому, когда мне приходится писать о каком-то общем положении — будь то второй закон термодинамики, компонент методики кодирования или полнофункциональная платформа программного обеспечения, я использую следующий подход в моём описании: понятие — логическая иллюстрация — пример. Я никогда не пытаюсь ввести какое-либо понятие без подкрепления логической иллюстрацией и дальнейшим примером.
Применим это правило для описания понятия элементарной алгебры.
Понятие «транзитивность отношения равенства» представляет собой следующее:
если A = B и B = C, то A = C;
Теперь приведём логическую иллюстрацию, описывающую это понятие (см. рис. 3).
Рис. 3. Транзитивность отношения равенства является фундаментальным принципом элементарной алгебры
Листинг 6 ниже показывает несколько конкретных примеров для закрепления понимания рассматриваемого положения.
Теперь рассмотрим понятие, которое ближе к разработке программного обеспечения и несколько труднее для понимания. Таким понятием является наследование моделей объектов проекта (POM = Project Object Model) в Maven (система автоматизированной сборки проектов). Пример 1 ниже представляет рассматриваемое понятие и даёт логическую иллюстрацию, описывающую это понятие. В конце представлена ещё одна иллюстрация, показывающее конкретное использование POM-файлов в ситуации наследования.
Пример 1: выдержка из технического описания наследования моделей объектов проекта (POM) в Maven (система автоматизированной сборки проектов)
Представление наследования POM-файла
POM-файл является XML-файлом, используемым для описания Maven-проекта и для работы с этим проектом. Можно задать, чтобы некоторый Maven-проект наследовал настройки из отдельного родительского POM-файла. Способность наследовать настройки из родительского POM-файла называется POM-наследованием. Вы используете элемент в вашем POM-файле, чтобы задать родительский POM-файл, из которого должно произойти наследование настроек.
Рис. 4 ниже показывает иерархию некоторого условного проекта, являющуюся примером задания мастер-файла РОМ, из которого другие РОМ-файлы могут наследовать общие настройки.
Рис. 4. Можно назначить мастер-файл РОМ, из которого будет происходить наследование общих настроек
Рис. 5 ниже показывает содержание POM.xml-фалов для Maven-проектов stooges-web, stooges-api и stooges-dal. Каждый проект сконфигурирован на использование элемента для наследования настроек из stooges-project.
Рис. 5. Использование элемента для управления Maven-проектом с целью наследования настроек из внешнего РОМ-файла
Пример выше опирается, в основном, на рисунки, чтобы обеспечить логическую иллюстрацию и показать конкретное использование рассматриваемого понятия. Подготовка интересных, привлекательных и точных иллюстраций и примеров является трудной задачей, но усилия стоят того. Создание множества иллюстраций для технического текста и примеров кода требует времени не меньше, чем написание самого текста. Соответственно я планирую моё время, чтобы выполнить работу в срок.
Итак, если требуется предельно ясно представить какое-то понятие, то необходимо включить в текст иллюстрации и примеры.
7. Не опасайтесь переделок
Редко удаётся написать хороший технический текст с первой попытки. Освоение темы, организация подходов и нахождение формы ясного и точного представления идей требует много времени и усилий. Поэтому не стесняйте себя ожиданием, что всё получится прямо с первого раза. Лучше планируйте пройти, как минимум, через три версии вашего творения. Первая версия представляет собой просто некоторый набор слов в печатном виде, давая вам возможность осознать ваши намерения. Вторая версия уже придаёт вашей работе ясность и точность. Затем, когда все факты в тексте проверены, иллюстрации выверены и структура логично выстроена, можно подготовить третью версию, которая будет привлекательной и своеобразной.
Можно сказать об этой работе, перефразируя известную цитату Томаса Эдисона: «Написание технического текста — это на 10% литературное творчество и на 90% переработка!»
Обещанный бонус
Теперь, когда вы знаете 7 правил для создания технической документации мирового класса, я хотел бы поделиться с вами изложением процесса, который я использую при подготовке технических текстов. Здесь немного, но по существу. Я называю этот процесс — ««7 шагов создания технического документа». Итак:
1. Составляю структуру, как минимум, до второго уровня (если удаётся, то и до третьего);
2. Добавляю иллюстрации в структуру для каждого понятия;
3. Делаю подписи под иллюстрациями;
4. Пишу текст в соответствии со структурой, соблюдая правило двух предложений и подстраивая структуру под текст;
5. Редактирую, переделываю;
6. Отправляю результат специалисту по рассматриваемой теме на рецензирование (специалистом по рассматриваемой теме является лицо, которое в состоянии выявить неточности и неясности в описании);
7. Снова редактирую работу на основе отзыва рецензента (рецензентов).
И вот они у вас: 7 правил, 7 шагов. Кому-то надо больше? Теперь, когда вы знаете все мои приёмы, двигайтесь свободно вперёд и делайте мир более правильным, привлекательным, ясным и интересным местом для жизни. Он заслуживает таких усилий.