21.01.2025 14:21
ENRUStudio 1 817 Источник

Большинство гайдов по программному обеспечению написаны трагически плохо.

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

Но есть и хорошая новость: научиться писать грамотные руководства проще, чем вы думаете. Следуйте нескольким простым правилам, и ваши тексты будут выделяться на фоне повсеместной посредственности.

Правила

  1. Пишите для чайников

  2. Пообещайте в заголовке чёткий результат

  3. Во введении объясните цель статьи

  4. Покажите конечный результат

  5. Разрешите копировать сниппеты кода

  6. Используйте длинные варианты флагов командной строки

  7. Разделяйте пользовательские значения и переиспользуемую логику

  8. Не загружайте читателя бессмысленными задачами

  9. Поддерживайте код в рабочем состоянии

  10. Посвятите гайд одной теме

  11. Не приукрашивайте

  12. Сократите зависимости по максимуму

  13. Чётко указывайте имена файлов

  14. Используйте единообразные содержательные заголовки

  15. Покажите, что ваше решение работает

  16. Увяжите конкретику с комплексным примером

Пишите для чайников

Самая распространённая ошибка гайдов — когда объяснение адресовано новичкам, а написано сложным экспертным языком.

Мастер-класс для начинающихНе пойму, почему никто не хочет попробовать скалолазание?
Мастер-класс для начинающих
Не пойму, почему никто не хочет попробовать скалолазание?

Руководства чаще всего читают начинающие. Или программисты с опытом, изучающие новое для них направление.

❌ Плохо: Использовать понятия, непонятные новичкам

В этом руководстве я расскажу, как создать первый SPA «Hello world» на React.

Откройте приложенный файл hello.jsx и измените приветствие с Hello world на Hello universe.

Для отображения нового текста браузер не перезагружается. За счёт эффективной транспиляции JSX в React изменения видны сразу же.

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

Приведённый выше пример отпугнёт новичков.

Разработчик, который ещё не работал с веб-фреймворком React, не понимает, что такое транспиляция JSX или механизм сверки. А если он не работал с другими фреймворками JavaScript, ему также будут незнакомы SPA, мягкая перезагрузка и виртуальный DOM.

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

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

✅ Хорошо: Применяйте термины, понятные новичкам

В этом руководстве я покажу вам, как создать простую веб-страницу с помощью современных инструментов веб-разработки.

Для этого я использую React, бесплатный популярный инструмент для создания сайтов.

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

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

Пообещайте в заголовке чёткий результат

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

  • Полное руководство о том, как стать гуру в CSV на Python

  • Как создать свой собственный Twitter
    Key Mime Pi: сделайте классный гаджет
    Как создать компилятор

Вот примеры слабых заголовков:

❌ Плохо

• Полное руководство о том, как стать гуру в CSV на Python
• Как создать свой собственный Twitter
• Key Mime Pi: сделайте классный гаджет
• Как создать компилятор

Это слабые заголовки, потому что они не поясняют, о чём текст. Из такого заголовка неясно, чему научит руководство. Заголовок должен лаконично объяснять, чего читатель может ожидать, ознакомившись с руководством. Вот как можно переписать предыдущие заголовки:

✅ Хорошо: Используйте заголовки, обещающие чёткий результат

• Как читать CSV-файл в Python
• Создайте клон Twitter в реальном времени за 15 минут — с помощью Phoenix LiveView
• Key Mime Pi: превратите Raspberry Pi в удалённую клавиатуру
• Как написать компилятор на Python и уложиться в 500 строк кода

Из этих заголовков совершенно ясно, чему научится читатель, ознакомившись с руководством.

Во введении объясните цель статьи

Если читатель открыл ваш гайд, это уже отличный старт: кому-то интересно, о чём вы пишете. Но вам всё ещё нужно убедить его, что стоит читать руководство дальше.

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

  1. Надо ли изучать эту технологию?

  2. А если надо, подходящее ли руководство я открыл?

Первые предложения статьи должны дать ответы на эти вопросы.

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

❌ Плохо

Введение в контейнеры Docker

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

В этом руководстве я покажу вам, как с помощью Docker запускать контейнеры в локальной инфраструктуре и в облаке.

Если судить по этому введению, какую проблему решает Docker? Кому стоит им пользоваться?

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

Ниже формулировка, в которой объясняется, как Docker устраняет боли читателя:

✅ Хорошо: Объяснять конкретный результат и преимущества

Как использовать Docker для надёжного деплоймента приложений

Боитесь трогать свой продакшн-сервер, потому что никто не знает, как наладить его работу после сбоя? Рвёте на себе волосы, потому что не понимаете, почему промежуточная рабочая среда работает не так, как продакшн-среда?

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

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

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

Во введении не сказано: «Это руководство для тех, кто ничего не знает про Docker». Но это и не нужно. В нём Docker описывается как новая концепция, так что всем понятно, что гайд для новичков.

Покажите конечный результат

Как можно скорее покажите на демо или скриншоте, что читатель сможет создать к концу гайда.

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

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

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

Разрешите копировать сниппеты кода

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

Удивительно, сколько гайдов не разрешают копирование. А ведь без этого читателю гораздо труднее проверить в деле примеры из статьи.

Разрешите копировать команды оболочки

Очень распространённая ошибка, связанная со сниппетами кода, — использование символа shell prompt.

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

$ sudo apt update       # <<< Don't do this!
$ sudo apt install vim  # <<< Users can't copy/paste this sequence without
$ vim hello.txt         # << picking up the $ character and breaking the command.

Даже в Google не удаётся скопировать её без косяков. В некоторых статьях услужливо предусмотрена кнопка «Скопировать образец кода».

В Google есть кнопка «Скопировать образец кода», но символы терминала оболочки копируются неправильно
В Google есть кнопка «Скопировать образец кода», но символы терминала оболочки копируются неправильно

Если нажать кнопку копирования, она скопирует $, символ приглашения терминала, так что вам не удастся вставить код:

michael@ubuntu: $ gcloud services enable pubsub.googleapis.com
$ gcloud services disable pubsub.googleapis.com
bash: $: command not found
bash: $: command not found
michael@ubuntu:

Есть и другой вариант этой ошибки, не такой заметный:

❌ Плохо: Последовательность команд, которую пользователю приходится вводить

sudo apt update

sudo apt install software-properties-common

sudo add-apt-repository ppa:deadsnakes/ppa

sudo apt install python3.9

Если я попытаюсь скопировать этот сниппет, вот что я увижу в терминале:

0 upgraded, 89 newly installed, 0 to remove and 2 not upgraded.
Need to get 36.1 MB of archives.
After this operation, 150 MB of additional disk space will be used.
Do you want to continue? [Y/n] Abort.
$

Что случилось?

При выполнении команды apt install software-properties-common требуется пользовательский ввод. А пользователь не может выполнить это действие, потому что apt просто считывает буфер обмена дальше.

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

✅ Хорошо: Используйте флаги командной строки, чтобы отказаться от интерактивного пользовательского ввода

sudo apt update

sudo apt install --yes software-properties-common

sudo add-apt-repository --yes ppa:deadsnakes/ppa

sudo apt install --yes python3.9

Объединяйте команды оболочки с помощью &&

Давайте вернёмся к примеру установки Python, который я приводил выше. В нём есть ещё одна проблема:

❌ Плохо: Игнорируются невыполненные команды

sudo apt update

sudo apt install software-properties-common

sudo add-apt-repository ppa:deadsnakes/ppa

sudo apt install python3.9

Пользователи не всегда замечают, что одна из команд завершилась с ошибкой. Например, если первая команда — sudo apt cache ppa:dummy:non-existent, она завершится с ошибкой, но оболочка радостно выполнит следующую команду, как будто до этого всё было отлично.

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

Вот удобный способ представить последовательность копируемых команд:

✅ Хорошо: Объединить команды с помощью &&

sudo apt update && \

sudo apt install --yes software-properties-common && \

sudo add-apt-repository --yes ppa:deadsnakes/ppa && \

sudo apt install --yes python3.9

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

Показывайте shell prompt, только чтобы продемонстрировать результат

Иногда символ shell prompt можно использовать для пользы читателя.

Если вы показываете команду и результат её выполнения, символ shell prompt помогает читателю различать, что он вводит и что получается в результате.

Например, в руководстве об утилите jq можно представить результаты следующим образом:

✅ Хорошо: Используйте символ shell prompt, чтобы провести различия между самой командой и результатом её выполнения

Утилита jq позволяет элегантно реструктурировать данные JSON:

$ curl \ --silent \ --show-error \ https://status.supabase.com/api/v2/summary.json | \ jq '.components[] | {name, status}' { "name": "Analytics", "status": "operational" } { "name": "API Gateway", "status": "operational" } ...

Исключите номера строк из копируемого текста

Указывать номера строк в сниппетах кода — это нормально. Но убедитесь, что они не мешают корректно копировать код. Например, если пользователь пытается скопировать функцию count_tables из следующего сниппета, ему придётся удалять номера строк из копируемого текста.

❌ Плохо: Номера строк включены в копируемый текст

123 def count_tables(form):

124 if not form:

125 return None

Используйте длинные варианты флагов командной строки

В утилитах командной строки часто предусмотрено два варианта одного и того же флага: короткий и длинный.

-r / --recursive : Run recursively
^      ^
|      |
|      long flag
|
short flag

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

❌ Плохо: Использовать короткие непонятные варианты флагов командной строки

Запустите эту команду, чтобы найти все страницы с элементами <span>:

grep -i -o -m 2 -r '<span.*</span>' ./

Даже если читатель знаком с инструментом grep, скорее всего, он не помнит наизусть все его флаги.

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

✅ Хорошо: Используйте подробные описательные варианты флагов командной строки

Запустите эту команду, чтобы найти все страницы с элементами <span>:

grep \ --ignore-case \ --only-matching \ --max-count=2 \ --recursive \ '<span.*</span>' \ ./

Разделяйте пользовательские значения и переиспользуемую логику

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

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

Используйте переменные среды в примерах командной строки

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

❌ Плохо: Выполните в коде действие bake с пользовательскими переменными

LOGS_ROUTE="$( curl \ --silent \ --header "X-Example-Token: YOUR-API-TOKEN" \ http://api.example.com/routes \ | grep "^logs " \ | awk '{print $2}' )" && \ curl \ --silent \ --header "X-Example-Token: YOUR-API-TOKEN" \ "http://api.example.com${LOGS_ROUTE}" \ | awk \ -F'T' \ '$1 >= "YYYY-MM-DD" && $1 <= "YYYY-MM-DD" {print $0}'

Какие значения заменять в этом примере?

Очевидно, нужно заменить плейсхолдер YOUR-API-TOKEN. А как насчёт YYYY-MM-DD? Вставлять ли на его месте реальные даты вроде 2024-11-23? Или он указывает на схему даты, в том смысле, что YYYY-MM-DD — это буквенное значение, которое надо оставить как есть?

В этом примере есть ещё несколько чисел и строк. А их заменять надо?

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

Вот как я переписал пример выше:

✅ Хорошо: Используйте переменные среды для пользовательских значений

API_TOKEN='YOUR-API-KEY' # Replace with your API key. START_DATE='YYYY-MM-DD' # Replace with desired start date. END_DATE='YYYY-MM-DD' # Replace with desired end date. LOGS_ROUTE="$( curl \ --silent \ --header "X-Example-Token: $API_TOKEN" \ http://api.example.com/routes \ | grep "^logs " \ | awk '{print $2}' \ )" && \ curl \ --silent \ --header "X-Example-Token: $API_TOKEN" \ "http://api.example.com${LOGS_ROUTE}" \ | awk \ -F'T' \ -v start="$START_DATE" \ -v end="$END_DATE" \ '$1 >= start && $1 <= end {print $0}'

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

Использование переменных среды проясняет назначение пользовательских значений. Благодаря этому пользователю придётся вводить каждое уникальное значение только один раз.

Используйте именованные константы в исходном коде

Представьте, что вы пишете руководство о том, как обрезать изображение, чтобы оно по формату подходило для постов в Bluesky и Х (ранее Twitter):

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

Вот как можно показать код для обрезки рисунка под размер картинки для поста.

❌ Плохо: Оставить читателя гадать, какие числа нужно заменить

func CropForSocialSharing(img image.Image) image.Image { targetWidth := 800 targetHeight := int(float64(targetWidth) / 1.91) bounds := img.Bounds() x := (bounds.Max.X - targetWidth) / 2 y := (bounds.Max.Y - targetHeight) / 2 rgba := image.NewRGBA( image.Rect(x, y, x+targetWidth, y+targetHeight)) draw.Draw( rgba, rgba.Bounds(), img, image.Point{x, y}, draw.Src) return rgba }

В примере четыре числа:

  • 800;

  • 1,91;

  • 2;

  • 2 (ещё раз).

Какие числа можно спокойно менять?

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

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

✅ Хорошо: Используйте переменные среды для пользовательских значений

// Use a 1.91:1 aspect ratio, which is the dominant ratio // on popular social networking platforms. const socialCardRatio = 1.91 func CropForSocialSharing(img image.Image) image.Image { // I prefer social cards with an 800px width, but you can // make this larger or smaller. targetWidth := 800 // Choose a height that fits the target aspect ratio. targetHeight := int(float64(targetWidth) / socialCardRatio) bounds := img.Bounds() // Keep the center of the new image as close as possible to // the center of the original image. x := (bounds.Max.X - targetWidth) / 2 y := (bounds.Max.Y - targetHeight) / 2 rgba := image.NewRGBA( image.Rect(0, 0, targetWidth, targetHeight)) draw.Draw( rgba, rgba.Bounds(), img, image.Point{x, y}, draw.Src) return rgba }

В этом примере значение 1.91 становится именованной константой, а код содержит комментарий, в котором объясняется, что это за цифра. Таким образом, читатель понимает, что значение не надо менять, поскольку в этом случае у изображения будут пропорции, не подходящие для картинки для поста.

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

Не загружайте читателя бессмысленными задачами

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

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

❌ Плохо: Загружать читателя ненужными утомительными действиями

Выполните следующие утомительные действия:

1. Запустите sudo nano /etc/hostname
2. Удалите имя хоста
3. Введите awesomecopter
4. Нажмите Ctrl + o, чтобы сохранить содержимое
5. Нажмите Ctrl + x, чтобы выйти из редактора

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

Лучше покажите читателю сниппет командной строки, который делает то, что ему нужно.

✅ Хорошо: Создайте скрипт для неинформативных и скучных действий

Вставьте следующую простую команду:

echo 'awesomecopter' | sudo tee /etc/hostname

Поддерживайте код в рабочем состоянии

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

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

Он хочет знать, что всё делает правильно. А для этого код должен быть в рабочем состоянии.

❌ Плохо: Ссылаться на код, который читатель ещё не видел

Вот код для примера. Но вы не занимайтесь его компиляцией. В нём не хватает функции parseOption, ха-ха!

// example.c #include <stdio.h> #include <stdlib.h> #include <string.h> #define MAX_LINE_LENGTH 256 int main() { char line[MAX_LINE_LENGTH]; char key[MAX_LINE_LENGTH]; char value[MAX_LINE_LENGTH]; while (fgets(line, sizeof(line), stdin)) { // Don't do this! parseOption(line, key, value); // <<< Not yet defined printf("Key: '%s', Value: '%s'\n", key, value); } return 0; }

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

$ gcc example.c -o example
example.c: In function ‘main’:
example.c:14:7: warning: implicit declaration of function ‘parseOption’
  [-Wimplicit-function-declaration]
   14 |       parseOption(line, key, value); // <<< Not yet defined
      |       ^~~~~~~~~~~
/usr/bin/ld: /tmp/ccmLGENX.o: in function `main':
example.c:(.text+0x2e): undefined reference to `parseOption'
collect2: error: ld returned 1 exit status

Как можно раньше покажите читателю пример, с которым он может работать. Опирайтесь на этот постулат и поддерживайте код в рабочем состоянии.

✅ Хорошо: Покажите пример, который пользователь сразу же может повторить, не забегая вперёд

// example.c #include <stdio.h> #include <stdlib.h> #include <string.h> #define MAX_LINE_LENGTH 256 void parseOption(char *line, char *key, char *value) { // Fake the parsing part for now. strncpy(key, "not implemented", MAX_LINE_LENGTH - 1); strncpy(value, "not implemented", MAX_LINE_LENGTH - 1); } int main() { char line[MAX_LINE_LENGTH]; char key[MAX_LINE_LENGTH]; char value[MAX_LINE_LENGTH]; while (fgets(line, sizeof(line), stdin)) { parseOption(line, key, value); printf("Key: '%s', Value: '%s'\n", key, value); } return 0; }

Теперь я протестирую программу, чтобы убедиться, что она работает:

$ gcc example.c -o example && \ printf 'volume:25\npitch:37' | \ ./example Key: 'not implemented', Value: 'not implemented' Key: 'not implemented', Value: 'not implemented'

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

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

Посвятите гайд одной теме

Хорошее руководство должно объяснять только одну вещь — и объяснять её хорошо.

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

❌ Плохо: Рассказывать одновременно о нескольких не связанных между собой идеях

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

Но это ещё не всё!

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

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

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

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

✅ Хорошо: Изложить в руководстве одну новую концепцию

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

В этом гайде я остановлюсь только на этом вопросе.

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

Иногда в руководстве приходится сочетать несколько технологий.

Например, у языка веб-программирования PHP нет встроенного рабочего веб-сервера. Чтобы показать, как задеплоить PHP-приложение в веб, вам придётся выбрать какой-то сервер, например: Apache, nginx или Microsoft IIS. Какой бы вариант вы ни выбрали, это оттолкнёт пользователей, которые предпочитают другой сервер.

Если вам нужно объединить несколько технологий, отложите это на конец гайда. Если пишете о PHP, постарайтесь как можно дольше продержаться на сервере разработки PHP. Если вы показываете, как задеплоить PHP-приложение в продакшн-среде на nginx, перенесите эти этапы на конец статьи. Тогда все, кто работает с другими серверами, смогут пройтись по этапам руководства до момента, когда вы дойдёте до раздела про серверы.

Не приукрашивайте

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

❌ Плохо

<div class="flex flex-row mb-4 overflow-hidden bg-white"> <div class="flex flex-col w-full p-6 text-light-gray-500"> <div class="flex justify-between mb-3"> <span class="uppercase">{{ title }}</span> </div> <slot></slot> </div> </div>

Думаете, это статья о фреймворке CSS? А вот и нет.

Этот сниппет — из руководства об использовании элемента <slot> в веб-фреймворке Vue. Так почему же половина кода приходится на классы CSS? Автор добавил их, чтобы пример смотрелся привлекательнее.

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

✅ Хорошо: Придерживайтесь простых демонстрационных UI, не зависящих от стиля

<div class="card"> <p class="card-title">{{ title }}</p> <slot></slot> </div>

Да, из этого упрощённого кода не получится красивая картинка, которая хорошо смотрится в браузере. Но это и не нужно. Зато таким образом можно доходчиво рассказать об элементе <slot>, не отвлекая читателя на посторонние моменты.

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

Сократите зависимости по максимуму

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

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

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

❌ Плохо: Удивить читателя зависимостями, которые трудно установить

Итак, мы добрались до пункта 12. Самое время установить ещё букет раздражающих вас программ, о которых я не упомянул раньше:

• Ffmpeg вместе с расширением libpita (скомпилированные двоичные файлы недоступны);
• специальная ветка Node.js, которую мой друг Марк Душнилз опубликовал в 2010 (для её компиляции понадобится Ubuntu 6.06);
• Perl 4.

Самые распространённые и фривольные зависимости, которые я вижу, — это библиотеки для парсинга дат. Вам тоже встречались подобные инструкции?

❌ Плохо: Добавлять сторонние зависимости для решения тривиальных задач

CSV-файл содержит даты в формате YYYY-MM-DD. Чтобы спарсить его, установите эту библиотеку на 400 МБ, предназначенную для парсинга любой строки данных в любом формате на любом языке и с любыми региональными настройками.

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

Мало того, что со сторонними инструментами сложнее следовать инструкциям в гайде, так ещё и каждая зависимость сокращает «срок службы» руководства. Возможно, через месяц внешняя библиотека выпустит обновление, из-за которого ваш код перестанет работать. Или издатель снимет библиотеку с публикации, и тогда ваш гайд станет вообще бесполезным.

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

Зафиксируйте определённые версии зависимостей

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

❌ Плохо: Использовать плохо определённые зависимости

Установите стабильную версию Node.js.

✅ Хорошо: Однозначно обозначить рабочие версии используемых зависимостей

Установите Node.js 22.x. Я тестировал это на Node.js v22.12.0 (LTS).

Чётко указывайте имена файлов

Больше всего меня бесит, когда автор руководства небрежно указывает: «Добавьте эту строку в файл конфигурации».

В какой именно файл конфигурации? Где именно?

❌ Плохо: Давать туманные инструкции о редактировании файла

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

optimization: { usedExports: true, minimize: true }

Если читателю нужно отредактировать файл, дайте ему полный путь к файлу и точно покажите, какую строку отредактировать.

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

✅ Хорошо: Конкретно указать, какой файл редактировать и где в нём будут изменения

Чтобы включить удаление неиспользуемого кода, добавьте следующий параметр оптимизации в module.exports файла конфигурации webpack:

// frontend/webpack.config.js module.exports = { mode: "production", entry: "./index.js", output: { filename: "bundle.js", }, // Enable tree-shaking to remove unused code. optimization: { usedExports: true, minimize: true, }, };

Используйте единообразные содержательные заголовки

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

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

Заголовки же структурируют статью. Большое руководство со множеством пунктов лучше разбить на несколько разделов, в каждом из которых будет по 5–6 подпунктов.

Пишите чёткие заголовки

Недостаточно просто разделить длинное полотно текста парой заголовков.

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

Какие из этих руководств вы бы предпочли? Эти?

❌ Плохо

1. Go
2. Установка
3. Hello, world!
4. Деплоймент

Или эти?

✅ Хорошо

1. Чем хорош Go
2. Установите Go 1.23
3. Создайте простое приложение Hello, World на Go
4. Как задеплоить приложение в веб

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

Сделайте заголовки единообразными

Перед публикацией гайда проверьте, точно ли у него единообразные заголовки.

❌ Плохо: Использовать заголовки вразнобой

1. Как я установил Go 1.23
2. Этап 2: ваше первое приложение
3. Как я упаковываю приложения на Go
4. Раздел D: как задеплоить приложение

Проверяя заголовки, обращайте внимание на следующие моменты:

  • Грамматические формы.
    Ваши заголовки — это именные или глагольные предложения?

  • От чьего лица ведётся повествование.
    Можно писать от первого лица («Я сделал X»), обращаться к читателю как к собеседнику («Сделайте X») или выбрать нейтральную манеру.

  • Грамматическое время.
    Вы пишете в настоящем, прошедшем или будущем времени?

Создайте с помощью заголовков логическую структуру

Убедитесь, что заголовки отражают логическую структуру руководства.

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

❌ Плохо: Использовать нелогичную структуру заголовков

1. Почему Go
1. История nginx
2. Конфигурируем локальный доступ в nginx
2. Создайте своё первое приложение на Go
1. Почему Go лучше, чем Perl
3. Поддержка базовой страницы

В приведённом примере у заголовка «Почему Go» есть подзаголовок «История nginx», хотя история nginx логически не является подтемой темы про Go.

Покажите, что ваше решение работает

Если в руководстве объясняется, как установить инструмент или интегрировать несколько компонентов, покажите, как использовать результат.

❌ Плохо: Показать установку и этим ограничиться

Наконец, выполните команду, чтобы активировать сервис nginx:

sudo systemctl enable nginx

Поздравляем! Готово!

Я предполагаю, что вы и так знаете, как действовать дальше, так что на этом моя миссия выполнена.

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

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

✅ Хорошо: Показать читателю, как взаимодействовать с инструментом

Наконец, выполните команду, чтобы активировать сервис nginx:

sudo systemctl enable nginx

Далее перейдите по этому URL-адресу в браузере:

• http://localhost/

Если всё работает, вы увидите nginx success page по умолчанию.

Success page в nginx
Success page в nginx

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

Увяжите конкретику с комплексным примером

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

Дайте ему ссылку на репозиторий со всем кодом, который вы показывали в руководстве. В идеале репозиторий лучше устроить в системе непрерывной интеграции вроде CircleCI или GitHub Actions, чтобы было видно, что ваш пример создан в актуальной среде.

Бонус: показывайте полный код на каждом этапе

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

Например, в руководстве «Как протестировать PDF-парсер с помощью Nix» я показываю читателю первую собираемую версию репозитория в собственной ветке:

В конце руководства даю ссылку на конечный результат:

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

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

Или открыть перспективы и получить повышение с профессиональным обучением:

Комментарии (1)


  1. PereslavlFoto
    21.01.2025 21:14
    #27814988

    Удивительно, сколько гайдов не разрешают копирование.

    Но ведь они защищают Авторские Права!