Самый популярный формат для написания текстов сейчас — Markdown. Тут будет не ещё один самоучитель, а описание некоторых неочевидных вещей.

1. Markdown позволяет использовать для отступов от 1 до 4 пробелов и даже табуляции. Я настоятельно рекомендую использовать 4 пробела. Если где-то в вёрстке ошибка, это сразу будет видно — неправильно оформленный кусок будет отформатирован как блок кода при сборке.

2. До и после списков и блоков кода обязательно нужно ставить одну пустую строку.

3. В конце файла должен быть переход на новую строку.

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

5. Если нужно показать результаты работы команды, используйте синтаксис text, а не bash. При использовании синтаксиса bash некоторые части кода будут выделены как ключевые слова:

   Text

   This value not acceptable in this position. Use value `1` for this parameter.
   

   Bash

   This value not acceptable in this position. Use value `1` for this parameter.
   

6. Не используйте $. Я не понимаю, зачем некоторые ставят этот знак в начале команд. Чтобы показать, что команду нужно выполнять без привилегий суперпользователя? А можно наоборот, использовать sudo, чтобы показать привилегии? Меня коробит от того, что я не могу просто скопировать фрагмент кода с помощью соответствующей кнопки — обязательно нужно править этот фрагмент, либо целиться с помощью мыши.

7. Разбивайте длинные команды на части с помощью \ и бэктиков `. Про бэктики узнал совсем недавно: оказывается, Bash игнорирует всё, что между ними, и это можно использовать, чтобы делить на части длинные команды. Как я потом узнал, разработчики PowerShell вовсе отказались от \, и там знак перехода на новую строку как раз бэктик `.

8. Используйте злые линтеры, например, markdownlint.

9. Выучите правила Markdown.