class: center, middle # Элементы стиля ## Как писать технические тексты --- # Что я знаю о текстах ??? Здравствуйте, меня зовут Марк Шевченко. Я программист. Наверняка у вас возникает вопрос: что я могу рассказать о технических текстах? --- # Что я знаю о текстах 1. [Сленг и фольклор программистов КАМАЗА](/articles/slang/) 1. [Сборник занимательных задач по языку программирования C](/articles/c-book-of-problems/) 1. [Документация к программе `arjz`](http://www.compression.ru/arctest/self/arjz.htm) 1. [Публикация в Компьютерре: Как разрабатывать корпортивный сайт](https://old.computerra.ru/1999/327/195478/) 1. [Публикации в журнале Upgrade](https://upweek.ru/kak-obyasnit-neposvyashhennomu-chto-takoe-programmirovanie) 1. [Ответы на Stack Overflow на русском](https://ru.stackoverflow.com/users/182162/mark-shevchenko?tab=answers) ??? Рассказать могу многое. Пишу давно и стараюсь писать хорошо. Если вы специалист, которому надо писать документацию, этот доклад для вас. На слайде — кое-что из написанного. --- # Предмет разговора ??? Речь будем вести о технических текстах. Их можно разделить на *учебные* и *справочные*. *Справочные* пишут для тех, кто «знал, но забыл». *Учебные* — для тех, кто не знает. --- # Предмет разговора * Справочники * Учебники ??? Мы будем говорить об *учебных текстах*. Рассмотрим их с точки зрения *содержания* и *формы*. --- # Предмет разговора * ~~Справочники~~ * Учебники * Содержание * Форма ??? Больше будем говорить про *форму*, поскольку, будучи специалистами, с содержанием работаем и так. Понимаем, а рассказать не можем. Но начнём всё-таки с содержания. Учебные тексты бывают разные и для начала давайте определим, с чем у нас проблем не возникает. Проблем не возникает с *фактами*. Лев Толстой родился в 1828 году. Всё понятно. Проблем не возникает с *инструкциями*. Если собирали икеевскую мебель, вы согласитесь — тоже всё понятно. Проблема возникает с *объяснением*, которое может быть *непонятным*. --- # Понимание текста ??? Что мешает пониманию? Например, сложная тема. --- # Понимание текста * Сложная тема ??? И интеллект читателей. --- # Понимание текста * Сложная тема * Глупые читатели ??? Обратите внимание на формулировки. При таких формулировках от нас ничего не зависит, и мы не можем исправить ситуацию. Мы не можем изменить тему, и не можем изменить читателей. Чтобы разобраться с проблемами, надо изменить формулировки. Для начала взглянем на определение слова *понимание*. --- # Понимание текста * Сложная тема * Глупые читатели *Понимание* — усвоение нового содержания, включение его в систему устоявшихся идей и представлений.<br/> https://ru.wikipedia.org/wiki/Понимание ??? Так значительно понятнее. Что здесь важно? Я бы выделил *объём* нового содержания, и наличие *устоявшихся идей и представлений* в голове читателя. --- # Понимание текста * ~~Сложная тема~~ Много новых знаний * Глупые читатели *Понимание* — усвоение нового содержания, включение его в систему устоявшихся идей и представлений.<br/> https://ru.wikipedia.org/wiki/Понимание ??? Теперь мы можем сказать, что *сложность темы* определяется *объёмом нового содержания*. В чём наш шанс? В том, что студентов учат от четырёх до шести лет. Мы точно не в этой весовой категории, нам не надо создавать учебный курс. Так что наш объём точно не очень велик, и мы можем им управлять. --- # Понимание текста * ~~Сложная тема~~ Много новых знаний * Детализация * Приоритезация * Глупые читатели *Понимание* — усвоение нового содержания, включение его в систему устоявшихся идей и представлений.<br/> https://ru.wikipedia.org/wiki/Понимание ??? Для управления объёмом, мы можем ограничить *уровень детализации*. Даже если мы знаем по теме всё, не обязательно это всё рассказывать в одном небольшом тексте. Ограничив объём знаний по глубине, мы затем можем выделить самое *важное*. Расставим приоритеты и расскажем о том, что важно. Так мы упростим тему. --- # Понимание текста * ~~Сложная тема~~ Много новых знаний * Детализация * Приоритезация * ~~Глупые читатели~~ Разрыв в знаниях *Понимание* — усвоение нового содержания, включение его в систему устоявшихся идей и представлений.<br/> https://ru.wikipedia.org/wiki/Понимание ??? Теперь об *устоявшихся идеях и представлениях* в голове читателя. Если мы сообщаем читателю факты, которые некуда встроить, возникает разрыв. Поэтому надо знать *уровень читателя* и строить мостик от старых знаний к новым. Иными словами, нам надо создать контекст, на фоне которого факты обретут смысл. --- # Понимание текста * ~~Сложная тема~~ Много новых знаний * Детализация * Приоритезация * ~~Глупые читатели~~ Разрыв в знаниях * Уровень читателя * Контекст *Понимание* — усвоение нового содержания, включение его в систему устоявшихся идей и представлений.<br/> https://ru.wikipedia.org/wiki/Понимание ??? Схема несложная. Давайте посмотрим, как это выглядит на практике. --- # Понимание текста — примеры *Позволяет вам выбрать между поддержкой LRF-1914 (по умолчанию) и отсутствием поддержки LRF-1914.<br /> Если вы хотите включить поддержку LRF-1914, выберите «Да» или нажмите «Y».<br /> Если вы не хотите включать поддержку LRF-1914, выберите «Нет» или нажмите «N».*<br /> Пример из [статьи](http://russian.joelonsoftware.com/PainlessSpecs/1.html) Джоэла Спольски ??? Джоэл Спольски в своей первой книге привёл пример плохой документации. Здесь мы не понимаем, что означает поддержка LRF-1914. Но мы также понимаем, что и автор этого не понимает. Это пограничный пример, когда, прежде чем выбирать уровень детализации и выстраивать приоритеты, нам необходимо освоить тему. Русская пословица гласит: «Учи других — и сам поймёшь!» Поэтому правило номер один: прежде, чем приступать к теме, подготовьтесь. Проясните всё, что неясно вам самим. --- # Понимание текста — примеры LRF это ??? Приведу пример такой подготовки. Я никогда не знал, что означает это самое LRF-1914, и я решил подготовиться. Оказалось, что это программисткий фольклор времён палеолита. Про функцию LRF программисты рассказывали маркетологам: «наше устройство умеет то и это, и ещё поддерживает LRF». LRF — это *Little Rubber Feet*, то есть *Резиновые ножки*. --- # Понимание текста — примеры LRF это Little Rubber Feet ??? Приведу пример такой подготовки. Я никогда не знал, что означает это самое LRF-1914, и я решил подготовиться. Оказалось, что это программисткий фольклор времён палеолита. Про функцию LRF программисты рассказывали маркетологам: «наше устройство умеет то и это, и ещё поддерживает LRF». LRF — это *Little Rubber Feet*, то есть *Резиновые ножки*. --- # Понимание текста — примеры *XAML — сравнительно простой декларативный язык программирования общего<br /> назначения, предназначенный для конструирования и инициализации объектов.<br /> На самом деле XAML представляет собой диалект XML с добавлением ряда<br /> правил, относящихся к элементам, атрибутам и их отображению на объекты,<br /> их свойства и значения свойств (помимо всего прочего).*<br /> Адам Натан, «Подробное руководство по WPF 4»<br /> <br /> <br /> <br /> ??? Здесь не определены приоритеты. Автор пытается уместить в одно определение всё, что он знает о XAML. Ему это не удаётся, и он беспомощно утверждает, что есть ещё что-то *прочее*. --- # Понимание текста — примеры *XAML — сравнительно простой декларативный язык программирования общего<br /> назначения, предназначенный для конструирования и инициализации объектов.<br /> На самом деле XAML представляет собой диалект XML с добавлением ряда<br /> правил, относящихся к элементам, атрибутам и их отображению на объекты,<br /> их свойства и значения свойств (помимо всего прочего).*<br /> Адам Натан, «Подробное руководство по WPF 4»<br /> <br /> <br /> <br /> *XAML — основанный на XML язык разметки для декларативного программирования приложений.*<br /> https://ru.wikipedia.org/wiki/XAML ??? Сравните с определением из Википедии. Здесь автор вычленил главное и рассказал об этом. --- # Понимание текста — примеры *RSS — это формат синдикации контента на основе XML.*<br /> Пример плохого объяснения из книги «Искусство объяснять».<br /> <br /> <br /> <br /> ??? Сейчас все знают, что такое RSS, так что пример устаревший. Но лет пятнадцать назад это приходилось объяснять. Вот пример объяснения, которое не учитывает знаний читателя и не создаёт контекст. --- # Понимание текста — примеры *RSS — это формат синдикации контента на основе XML.*<br /> Пример плохого объяснения из книги «Искусство объяснять».<br /> <br /> <br /> <br /> *Время от времени я читаю новости в интернете. У меня есть любимые сайты, и<br /> несколько раз в день я проверяю, что там нового. С каждым днём<br /> интересных сайтов становится всё больше, и я всё больше времени трачу на<br /> проверку. Если бы можно было собрать все новости в одном месте,<br /> я бы не терял столько времени. RSS решает эту задачу.* ??? Я не нашёл в интернете примера, который бы меня устроил, поэтому написал его сам. Здесь создаётся контекст, чтобы объяснить, что такое RSS. Несложно, правда? Теперь перейдём ко другому аспекту технического письма, а именно к форме. --- # Стиль ??? Можно сказать, что *содержание* относится к вопросу *что* — что мы хотим донести? *Форма* относится к вопросу *как* — как донести? Мы поговорим о стиле написания. Будем опираться на опыт писателей и на собственный опыт программирования. --- # Стиль * Опыт писателей * Опыт программирования ??? Опыт писателей — это, например, «Краткость — сестра таланта». --- # Опыт писателей ## Кратко *Принципал предоставляет Агенту корневой сертификат Принципала (для обеспечения доверия сертификатам, выданным Центром сертификации Принципала) в виде, пригодном для установления его принадлежности Принципалу, то есть в виде base-64 кодированного файла формата PKCS#10 и на бумажном носителе, заверенном собственноручной подписью руководителя и оттиском печати Принципала.*<br /> Одна реальная документация<br /> <br /> <br /> ??? Текст из реальной документации. Видимо, что автор старается быть очень точным в деталях. Он пять раз упоминает *Принципала*, и уточняет, как именно хранить сертификат. Подпись руководителя должна быть именно *собственноручной*. Подписывать сертификат чужой рукой начальнику нельзя. --- # Опыт писателей ## Кратко *Принципал предоставляет Агенту корневой сертификат Принципала (для обеспечения доверия сертификатам, выданным Центром сертификации Принципала) в виде, пригодном для установления его принадлежности Принципалу, то есть в виде base-64 кодированного файла формата PKCS#10 и на бумажном носителе, заверенном собственноручной подписью руководителя и оттиском печати Принципала.*<br /> Одна реальная документация<br /> <br /> <br /> *Принципал предоставляет Агенту корневой сертификат в файле формата PKCS#10, и в бумажном виде с печатью и подписью руководителя.* ??? Текст после сокращения. Вряд ли он стал менее понятным. По своему опыту могу сказать, что в данном случае лучше потратить время на объяснение сертификатов. Тема сложная. Текст должен быть не только кратким, но и правдивым. Вместо *оценок* мы должны предоставлять *факты*. --- # Опыт писателей ## Честно *Мгновенная загрузка компьютера.*<br /> Пример из книги «Пиши, сокращай».<br /> <br /> <br /> ??? Здесь автор за вас принимает решение, быстро или медленно загружается компьютер. --- # Опыт писателей ## Честно *Мгновенная загрузка компьютера.*<br /> Пример из книги «Пиши, сокращай».<br /> <br /> <br /> *Благодаря твёрдотельному диску компьютер загружается за три секунды.* ??? Но он может предоставить нам факт, и мы решим сами. Более того, здесь мы понимаем, почему загрузка быстрее, чем раньше. Следущий шаг — убираем штампы. --- # Опыт писателей ## Без штампов *XX век **стал переломным** в вопросе грамотности населения. Люди научились читать, писать, считать и даже начали получать высшее образование. Благодаря этому, сегодня технический прогресс шагает **семимильными шагами**. У нас есть радио и телевидение, телефоны и компьютеры. Человек даже полетел в космос. В XXI же веке программирование стало **новым стандартом** грамотности.*<br /> https://lifehacker.ru/nuzhno-uchit-programmirovanie/<br /> <br /> <br /> <br /> ??? Я нашёл текст и выделил в нём штампы. Этот текст не выглядит *плохим*. Почему же вредны штампы? Потому что штампы это бывшие метафоры. Образы, потерявшие свою образность. Если вместо штампа вы напишите обычные слова, текст ничего не потеряет. --- # Опыт писателей ## Без штампов *XX век **стал переломным** в вопросе грамотности населения. Люди научились читать, писать, считать и даже начали получать высшее образование. Благодаря этому, сегодня технический прогресс шагает **семимильными шагами**. У нас есть радио и телевидение, телефоны и компьютеры. Человек даже полетел в космос. В XXI же веке программирование стало **новым стандартом** грамотности.*<br /> https://lifehacker.ru/nuzhno-uchit-programmirovanie/<br /> <br /> <br /> <br /> *В XX веке, когда высшее образование стало общедоступным, выросло число учёных и инженеров. Они ускорили технический прогресс и за короткое время мы получили радио, телевидение, телефоны, комьютеры, даже полёты космос. А в XXI веке, чтобы быть учёным и инженером, вы должны уметь программировать.* ??? Внизу мысль автора выражена компактнее. Сейчас она выглядит спорной. Похоже, автору следует изменить мотивацию в тексте. Увидеть слабость мотивации мы смогли из-за того, что избавились от штампов. Избавляйтесь от штампов — и вы поймёте, как улучшить свой текст! Следующий принцип я лично считаю самым важным. Простота. --- # Опыт писателей ## Просто *Мы стремимся собрать здесь слова, задающие философскую, интуитивно универсальную основу информатики. Эти слова достаточно неожиданно всплывали из небытия и удивительным образом исполнялись смыслом. Они стали своебразными точками входа в храм философствующих информатиков. Конечно, будут встречаться слова и поприземлённее: азбучные концепции, полезные слова-связки — слова, которые из песни не выкинешь.*<br /> https://ru.wikibooks.org/wiki/Словарик_философствующего_информатика<br /> <br /> <br /> <br /> ??? *Параллелизм* и *алгоритм* можно считать философскими основами иформатики, а можно — обычными терминами. Второе проще. --- # Опыт писателей ## Просто *Мы стремимся собрать здесь слова, задающие философскую, интуитивно универсальную основу информатики. Эти слова достаточно неожиданно всплывали из небытия и удивительным образом исполнялись смыслом. Они стали своебразными точками входа в храм философствующих информатиков. Конечно, будут встречаться слова и поприземлённее: азбучные концепции, полезные слова-связки — слова, которые из песни не выкинешь.*<br /> https://ru.wikibooks.org/wiki/Словарик_философствующего_информатика<br /> <br /> <br /> <br /> *Мы решили собрать словарь программиста*. ??? Помним, что мы пишем технический текст и часть сложных терминов вполне оправдана. Простота не в ущерб точности. Есть у писателей рекомендации и совершенно технического характера. --- # Опыт писателей ## Активно *Поле `foo` **было изменено** методом `bar`*.<br /> *Программа осуществляет **копирование** файла.*<br /> <br /> <br /> <br /> ??? *Страдательный залог* и *отглагольные существительные* заменяем на *активный залог* и *глаголы*! --- # Опыт писателей ## Активно *Поле `foo` **было изменено** методом `bar`*.<br /> *Программа осуществляет **копирование** файла.*<br /> <br /> <br /> <br /> *Метод `bar` **изменил** поле `foo`.*<br /> *Программа **копирует** файл.* ??? Попутно убираем *причастия*, *деепричастия* и половину *прилагательных*. Текст становится короче, потому что мы убираем слова *было* и *осуществляет*, которые не несут смысловой нагрузки. Текст становится проще, потому что в активных предложениях прямая логика. Из А следует Б, из Б следует Ц, значит, из А следует Ц. При страдательном залоге логика обратная: Ц следует из Б, который в свою очередь следует из А, значит, Ц следует из А. Теперь взгляем на опыт программирования. Программа это тоже выражение мыслей. Есть устоявшиеся правила, как писать чистый код, и некоторые из них подходят в техническим текстам. --- # Опыт программирования ## Устоявшаяся терминология *Алиасинг (aliasing) — это, возможно, наиболее фундаментальный и самый широко обсуждаемый артефакт 3D-рендеринга всех времён.*<br /> https://habr.com/post/343876/<br /> <br /> <br /> <br /> ??? Не придумывайте новые термины, когда есть известные старые. --- # Опыт программирования ## Устоявшаяся терминология *Алиасинг (aliasing) — это, возможно, наиболее фундаментальный и самый широко обсуждаемый артефакт 3D-рендеринга всех времён.*<br /> https://habr.com/post/343876/<br /> <br /> <br /> <br /> *Эффект лестницы (aliasign) — это, возможно, наиболее фундаментальный и самый широко обсуждаемый артефакт при отрисовке трёхмерных моделей.* ??? Здесь спорная замена. Доводя до абсурда можно спросить: на отказаться ли тогда и от англицизма *файл*? Про *файл* скажу — нет, не отказаться. Но англицизмы и прямая калька не всегда уместны в формальном тексте. Почитайте существующую литературу, поищите термины. *Лестничный эффект* и *ступечатость* были в советском издании книги Дэвида Роджерса Алгоритмические основы машинной графики 1989-го года. --- # Опыт программирования ## Одно понятие — одно слово *Сто первая строка программы выводит строку «ABC» в тринадцатую строку таблицы.* *Агент, Мерчант, Принципал... Оператор!* ??? Следуйте правилу: одна концепция — одно слово. Называть два разных понятия одним словом и одно понятие двумя словами неправильно. В документации по одной плтёжной системе определили понятия *агент*, *мерчант* и *принципал*. А ниже в тексте использовали термин *оператор*. Программистам пришлось писать в платёжную систему, чтобы узнать, кто именно имеется в виду. --- # Опыт программирования ## Нет каламбурам *Кто такие таксисты в зелёном озере?* *Класс `Foo` это племянник класса `Bar`.* ??? Помимо каламбуров воздержимся от остроумия и поэтических образов. Всё это может быть непонятно. У нас в системе управления такси про свободных таксистов мы говорили, что они в *зелёном озере*. Это неочевидно. В техническую документацию это понятие вносить не надо. В иерархии классов, опираясь на понятия *родительский* и *дочерний*, класс действительно можно обнаружить *классы-племянники*. Но эта терминология нестандартна и может быть непонятной. --- # Опыт программирования ## Простые абзацы, простые предложения *Не то чтобы это покалечило чьи-то судьбы, но изучение программных дисциплин могло бы проходить гораздо быстрее, если на стадии закладки фундамента мы представили многообразие языков и подходов, а не зомбически учили C++ в его консольных проявлениях.*<br /> https://geekbrains.ru/posts/programming_types<br /> <br /> <br /> ??? Большой абзац показывает, что автор не проработал материал. Как мы помним, в самом начале надо убрать несущественные *детали*. *Консольные проявления* затемняют главную мысль: давайте обучать первокурсников разным парадигмам. --- # Опыт программирования ## Простые абзацы, простые предложения *Не то чтобы это покалечило чьи-то судьбы, но изучение программных дисциплин могло бы проходить гораздо быстрее, если на стадии закладки фундамента мы представили многообразие языков и подходов, а не зомбически учили C++ в его консольных проявлениях.*<br /> https://geekbrains.ru/posts/programming_types<br /> <br /> <br /> *Изучение единственного языка C++ на первом курсе затрудняет изучение других языков в дальнейшем. Лучше дать студентам представление о разных парадигмах, а затем углублять его на материале конкретных языков программирования.* ??? После правки текст не стал короче, но стал понятнее. Мы заменили простую критику конструктивной, предложили решение, которое считаем лучшим. --- # Опыт программирования ## Непрерывный текст *Разработка правил есть поистине творческая задача. До сих пор был предложен, по-видимому, всего один метод структурирования информации (особенно тогда, когда ее слишком много): разделяй и властвуй².*<br /> <br /> ²Как тут не вспомнить Гради Буча и древних римлян! ??? Непрерывный текст можно читать подряд, не перескакивая с места на место. Надо избавиться от сносок, и надо группировать материал так, чтобы следствия шли сразу за посылками. В приведённом примере автор грешит дважды: захотел показаться умным в ущерб простоте, и недостаточно разобрался в теме. Я знаю, потому что автор я. Да, правило *разделяй и властвуй* придумали древние римляне. Да, о нём писал Гради Буч. Но сноска не несёт никакой полезной информации. От сносок лучше избавляться совсем, потому что читатель в этом месте должен будет остановиться, найти комментарий, прочитать, и затем вернуться к месту, где он прервал чтение. --- # Опыт программирования ## Один уровень детализации *Во-первых, все члены команды верстальщиков должны придерживаться единого стиля оформления страницы (это касается и HTML, и CSS, и скриптов).*<br /> <br /> <br /> <br /> ??? Продолжением правила непрерывного текста является один уровень детализации на предложение. Если вы хотите написать что-то в скобках, вы пытаетесь вставить в предложение лишнюю подробность. Если подробность не лишняя, напишите о ней без скобок. Читатель на скобках *спотыкается*. --- # Опыт программирования ## Один уровень детализации *Во-первых, все члены команды верстальщиков должны придерживаться единого стиля оформления страницы (это касается и HTML, и CSS, и скриптов).*<br /> <br /> <br /> <br /> *Во-первых, все члены команды верстальщиков должны придерживаться единого стиля оформления кода.*<br /> ??? Программисты говорят об одном уровне абстракции на функцию. --- # Литература [Искусство объяснять](https://www.mann-ivanov-ferber.ru/books/paperbook/art-explanation/), Ли Лефевер<br /> [Пиши, сокращай](https://book.glvrd.ru/), Максим Ильяхов, Людмила Сарычева<br /> [Чистый код](https://www.piter.com/collection/all/product/chistyy-kod-sozdanie-analiz-i-refaktoring-biblioteka-programmista-197984), Роберт Мартин ??? ### Три книги, которые я использвал при подготовке документации. Книга «Искусство объяснять» из современных многословных изданий. 240 страниц на три действительно важные темы. Куча картинок. Если жалко денег, не покупайте. В книге можно прочитать про разрыв в уровне знаний. Не знаю, как книга читается по английски, но по русски скучно. Вторую книгу, наоборот, покупайте за любые деньги. Она — лучшее, что есть для авторов, не получивших профильного образования. Да и тем, кто такое образование получил, книга не повредит. Всё, что касатеся стиля, штампов, простоты, краткости, всё в ней есть, всё с примерами, и всё про русский язык. Третья книга про то, как писать простой код. Программисты её знают и часто на неё ссылаются. --- class: center, middle Марк Шевченко<br /> https://markshevchenko.pro