База знаний
Войти

Оформление документации с акцентом на действия пользователя

Этот документ определяет, как выделять элементы, с которыми пользователь должен взаимодействовать напрямую: копировать, вводить, редактировать, проверять или на которые нужно обратить внимание. Цель — сделать инструкцию максимально «исполняемой» и снизить риск ошибок.

1. Что выделять

Выделяйте только то, что:

  • пользователь копирует целиком (команды, конфиги, ключи);
  • пользователь вводит вручную (PIN-коды, имена, пути);
  • пользователь должен найти и изменить (строки в конфигурационных файлах);
  • требует особого внимания (предупреждения, критичные замечания).

Не выделяйте описательные термины (например, «модуль PAM», «токен»), если они не используются как ввод/вывод.

2. Команды для копирования

Оформляйте только исполняемые команды как блоки кода с языком bash.
Не включайте пояснения внутрь блока.

Пример:

sudo dnf install pam_p11

Не делайте так:

Выполните: sudo dnf install pam_p11 — это снижает читаемость и мешает копированию.

3. Значения, вводимые пользователем

Все значения, которые пользователь вводит вручную (PIN, имя пользователя, IP и т.п.), выделяйте как inline-код:

  • PIN-код: `12345678`
  • Имя пользователя: `alice`
  • Порт: `22`
  • IP-адрес: `192.168.1.10`

Это помогает отличить «что вводить» от «что система покажет».

4. Конфигурационные фрагменты

Если пользователь должен вставить или заменить часть конфигурации — приводите точный фрагмент как блок кода с указанием языка (pam, ini, text и т.д.).

Пример (замена в /etc/pam.d/login):

auth [default=1 success=ignore] pam_succeed_if.so user ingroup tokenlogin
auth substack p11
auth [default=ignore success=1] pam_succeed_if.so user ingroup tokenlogin
auth substack system-auth

Важно! Не смешивайте «старый» и «новый» код в одном блоке. Четко указывайте: «замените строку X на блок Y».

5. Пути к файлам и имена файлов

Все пути и имена файлов, которые пользователь должен открыть, создать или проверить, выделяйте как inline-код:

  • Откройте файл `/etc/pam.d/p11`
  • Создайте каталог `~/.ssh`
  • Проверьте наличие файла `/etc/role`

6. Комбинации клавиш

Выделяйте как inline-код, если они нужны для выполнения действия:

  • Сохраните файл: нажмите `Ctrl+O`, затем `Enter`
  • Переключитесь в TTY: `Ctrl+Alt+F2`

7. Предупреждения и важные замечания

Используйте явные префиксы и выносите в отдельный абзац с цитатой (>):

Предупреждение. Отключение pam_gnome_keyring обязательно — иначе вход по токену не сработает.

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

8. Что НЕ выделять

Не оформляйте как код:

  • Общие термины: PAM, SSH, PKCS#15, Рутокен — если они не являются частью ввода.
  • Описания действий: «после этого система запросит PIN» — без выделения.
  • Имена пакетов в тексте, если они не входят в команду:
    «Установите пакет pam_p11» → только если далее идёт команда.
    Не выделяйте «пакет task-smartcards» просто в предложении.

9. Пример хорошей структуры шага

Откройте файл `/etc/pam.d/gdm-password`:

sudo nano /etc/pam.d/gdm-password

Замените строку:

auth        substack      password-auth

на следующий блок:

auth [default=1 success=ignore] pam_succeed_if.so user ingroup tokenlogin
auth substack p11
auth [default=ignore success=1] pam_succeed_if.so user ingroup tokenlogin
auth substack password-auth

Предупреждение. Также закомментируйте строку с pam_gnome_keyring.so — она конфликтует с аутентификацией по токену.

10. Общее правило

Если пользователь должен это скопировать, ввести, найти или изменить — выдели.
Если это просто объяснение — не выделяй.

Это делает документ «рабочим инструментом», а не просто описанием.