Как Писать Технические Тексты

Стиль Повествования

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

---

Было

А вы знаете, что в языке JavaScript целых 8 типов данных? О, да, этот язык полон сюрпризов! Среди них — не только знакомые нам строки и числа, но и такие экзотические типы, как Symbol и BigInt.

Без паники! В этой статье мы рассмотрим все типы данных.

Каждый тип данных — это ключ к новой загадке, которую JavaScript готов вам предложить. Давайте погрузимся в это увлекательное путешествие по миру данных, и кто знает, какие чудеса нас ждут на этом пути!

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

Такой стиль не подходит для образовательного контента. Шутки в тексте отвлекают от содержимого и раздражают. Исправим это:

---

Стало

В JavaScript 8 типов данных, включая строки, числа, Symbol и BigInt.

Отглагольные Существительные

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

Проблема отглагольных существительных в том, что они перегружают текст, убирают из него действие, делают текст неживым, сухим и скучным.

Пример текста с отглагольными существительными:

---

Было

Внедрение Nuxt.js в проекты фронтенд-разработки облегчает создание универсальных приложений. Упрощение настройки и конфигурации делает старт проектов быстрым.

Использование серверного рендеринга повышает производительность и улучшает SEO.

Интеграция с Vue.js способствует разработке интерактивных пользовательских интерфейсов.

Заменим отглагольные существительные на глаголы и вдохнём в этот текст жизнь:

---

Стало

Nuxt.js упрощает создание универсальных фронтенд-приложений. Быстрый старт проекта достигается простой настройкой конфигурации.

Серверный рендеринг ускоряет загрузку страниц и улучшает SEO.

Благодаря совместимости с Vue.js, разработчики легко создают интерактивные пользовательские интерфейсы.

Не используйте отглагольные существительные.

Страдательный Залог

Страдательный залог показывает, что действие совершает не субъект, а что действие совершается над субъектом. Этот стиль похож на язык чиновников.

Страдательный залог усложняет чтение и обычно легко заменяется на действительный залог.

Действительный залог делает предложения более прямыми и понятными. Рассмотрим пример:

---

Было

GraphQL был разработан Facebook для упрощения процессов обмена данными между клиентом и сервером.

В его основе лежит использование типизированной системы запросов, которая позволяет клиентам точно определять, какие данные им необходимы. Благодаря этому, избыточная загрузка данных была существенно сокращена, а производительность клиентских приложений повышена.

---

Стало

Facebook разработал GraphQL, чтоб упростить обмен данными между клиентом и сервером.

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

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

Желательно от него избавиться.

Повелительное Наклонение

Повелительное наклонение добавляет динамику в текст, стимулирует к действию и используется для прямого обращения к читателю.

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

---

Было

Проект на Vue может быть инициализирован с помощью следующей команды:

Bash

npm create vue@latest

---

Стало

Выполните команду, чтоб создать проект на Vue:

Bash

npm create vue@latest

Также повелительное наклонение позволяет формулировать мысли кратко и лаконично.

Используйте повелительное наклонение.

Абзацы

Делите текст на абзацы. Абзацы наводят порядок в тексте.

Одна мысль — один абзац.

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

Короткие Предложения

Избегайте длинных предложений. В жизни мы общаемся короткими предложениями. Когда текст приближен к разговорной речи, его легче читать и воспринимать.

---

Было

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

---

Стало

Короткие предложения читаются легко. Они быстрые и ясные. Каждая идея отделена. Это помогает пониманию. Наш мозг не перегружается. Информация усваивается быстрее.

Синтаксис

Упрощайте синтаксис в тексте.

Мы делаем паузы на каждом знаке препинания, когда читаем текст.

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

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

Заголовки и Списки

Так же, как и код, технические тексты должны быть модульными.

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

Хорошо структурированный текст делает процесс изучения более эффективным и приятным.

Пишем Введение

Читателю важно понимать, стоит ли ему тратить время на прочтение статьи. Поэтому введение может начинаться с объяснения пользы статьи. Ответьте читателю на его вопросы:

• С какой концепцией я познакомлюсь в статье?
• Что я смогу сделать после прочтения статьи?
• Зачем это нужно?

Пишем Заключение

Задача заключения — сделать выводы и дать практические советы по использованию изученного материала.

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

Доступность

Минимизируйте количество терминов и сокращений, если это возможно. Незнакомые термины вызывают отторжение у новичков, а их обилие снижает мотивацию к изучению контента.

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

Помните, читатели это люди с разным уровнем технических знаний. Делайте тексты доступными для всех.

Объясняйте причины и следствия. В технических текстах важно не только показать, как что-то делается, но и почему это важно.

Тут важно не скатиться в описание совсем простых вещей.

---

Поле ввода — это функциональный компонент, который даёт возможность пользователям вводить значения с помощью клавиатуры.

Какие вещи стоит объяснять, а какие нет, нужно решить самостоятельно. Есть такая штука, как проклятие знания. Это когда человек, который знает какую-то тему хорошо не может её легко объяснить новичкам, потому что не может себя представить себя на их месте.

Ёмкость

У нас у всех мало свободного времени. Мы все хотим получить пользу от контента как можно быстрее.

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

Фразы «обратите внимание», «стоит упомянуть», «важно уточнить, что» нарушают естественный поток текста и прерывают внимание читателя. Их в тексте не должно быть.

Краткость

Если текст можно сократить, его нужно сократить. Не используйте вводные слова, причастия, деепричастия, глаголы в страдательном залоге, синонимы при описании.

---

Было

Использование систем контроля версий, таких как Git, представляет собой важный и существенный аспект разработки программного обеспечения, поскольку они позволяют разработчикам отслеживать и управлять изменениями в коде. Таким образом, это жизненно необходимый для совместной работы и эффективного управления проектами инструмент.

---

Стало

Git — инструмент для отслеживания изменений в коде и совместной работы над проектами.

Ещё пример:

---

Было

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

---

Стало

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

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

Объективность

Никогда не давайте необъективных оценок. Расплывчатые формулировки нужно удалять, либо подкреплять фактами.

Например:

---

Было

TinyJS — это быстрая и легковесная библиотека для управления состоянием для множества фреймворков.

Данное предложение звучит неубедительно как раз из-за отсутствия доказательств. Говорите правду, даже если она неудобная:

---

Стало

TinyJS — легковесная библиотека (2 kB) для управления состоянием в React и Preact.

Бенчмарки:

…

Однозначность

Неоднозначность в тексте может создавать путаницу в головах начинающих разработчиков. Выражайтесь однозначно и прямолинейно.

---

Было

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

---

Стало

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

Оценки

Откажитесь от субъективных оценок, такие вещи подрывают доверие читателя. В тексте не должно быть предвзятых и необоснованных суждений. Любые оценочные суждения должны сопровождаться доказательствами.

---

React на сегодняшний день является лучшим фреймворком.

---

Все знают, что такое ООП.

Визуализация

Диаграммы, схемы, скриншоты и примеры кода улучшают понимание технических деталей. Читать их проще, чем текст.

---

Было

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

Если бы мы использовали код, текст стал бы понятным:

---

Стало

Создайте градиентный фон в CSS:

CSS

.section {
  background: linear-gradient(direction, start-color, end-color);
}

• direction: направление градиента,
• start-color: начальный цвет,
• end-color: конечный цвет.

Переменные

Выразительные имена переменных позволяют писать код без комментариев. Подходите к выбору имени переменных ответственно.

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

Если значение переменной — объект или примитив, переменные следует обозначать существительным:

• user
• age

Если массив, то существительное во множественном числе:

• users

Названия функций должны начинаться с глагола:

• getUserInfo()
• downloadCSV()

Для обработчиков событий обычно используется приставка on или handle:

• onSubmit
• handleNameChange

Логические значения обычно начинаются со слов is или has:

• isAdmin
• hasValue

Никогда не используйте магические числа. Магическими они называются потому, что нельзя сходу определить, откуда они взялись и что означают.

---

Было

JavaScript

let blockSize = 20 * 8

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

---

Стало

JavaScript

let elementWidth = 20
let numberOfElements = 8
let blockSize = elementWidth * numberOfElements

Импорты

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

---

Было

JavaScript

export let getDirname = () => {
  let filename = url.fileURLToPath(import.meta.url)
  return path.dirname(filename)
}

---

Стало

JavaScript

import path from 'node:path'
import url from 'node:url'

export let getDirname = () => {
  let filename = url.fileURLToPath(import.meta.url)
  return path.dirname(filename)
}

Простота

Примеры кода важны, они делают текст практичным и полезным.

Если в тексте объясняется сложная концепция, начните с простых примеров кода и постепенно углубляйтесь, добавляя детали или функциональность.

Стремитесь к тому, чтобы код был понятным и простым. Сложные конструкции пугают читателей.

Если пример кода всё-таки большой и сложный, добавьте комментарии к коду. И обязательно дополнительно объясните, как он работает. Комментарии к коду не заменяют текст.

Команды

После выполнения команд в терминале всегда следует показывать ожидаемый результат.

---

Для установки NodeJS выполните команду:

Bash

brew install node

Убедитесь, что NodeJS был успешно установлен:

Bash

node -v

Антипаттерны

Если есть примеры как писать код не нужно, то это стоит подсветить. Например, условия, которые приводят выполнение программы к бесконечному циклу.

Актуальность

Регулярно обновляйте уже опубликованные тексты. Технологии быстро меняются, поэтому важно поддерживать актуальность контента.

Всегда проверяйте, что примеры кода работают.

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