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

[PereslavlFoto]

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

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

[Edreyn]

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

[LexD1]

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

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

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

Да, есть такое. А ещё не единожды встречал примеры, где комментарий не закомментирован, а закомментирован код:

Создадим папку для логов
# mkdir /tmp/MyLogs

Для копирования обычно дважды щёлкаю ЛКМ на строке, Ctrl+C, Ctrl+V. В результате код копируется с символом "#" ("$") в начале. Приходится либо удалять ненужный символ (плюс пробел) после вставки, либо копировать строку не двойным щелчком, а выделением мышью, что дольше.

Вероятно, создатели подобных гайдов сами тупо (не понимая?) копируют код из терминала с начальным символом "$".

Зачем комментировать код, а не комментарий так и не понял.

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

1. Запустите sudo nano /etc/hostname

2. Удалите имя хоста
3. Введите awesomecopter

4. Нажмите Ctrl + o, чтобы сохранить содержимое
5. Нажмите Ctrl + x, чтобы выйти из редактора

А вот здесь не соглашусь. Речь же о новичках? Мне, допустим, понятнее использование текстового редактора (nano, vim, xed, mousepad, не суть), нежели строки кода, да ещё и с конвейером. И утомительных действий здесь не вижу, ибо понятнее. Возможно, стоит предложить оба варианта, но так получится громоздко и избыточно.