Comments 11
Потрясающе, взяла все в работу
Отлично! И да, я видел некоторое дерьмо такую документацию.
Впишу в Styleguide
Дополню в комменты к https://habr.com/ru/articles/830584/
Чтобы сохранить проект, в правой верхней части окна нажмите Сохранить
А почему его зовут «Хрен попадешь»? — Потому что в него хрен попадешь :)
Статья хорошая, но недостаточно. Например, не упомянут простой но эффективный метод совершенствования: после того, как написали весь текст до конца, просто удалите несколько абзацев, выбирая их в случайном порядке. Достаточно удалить процентов 10, что бы получить весьма мощный эффект. После этого важно не перечитывать оставшийся текст, ибо в противном случае бороться с желанием что то подредактировать будет сложно. А нам авторам сложности не нужны.
Еще рекомендация: если есть возможность написать математическую формулу, ни в коем случае не используйте знак умножения. Во первых не писать знак умножения традиционно для нашей технической литературы, во вторых - эффективно. Вот пример:
Wк=Пиhк((0.5DВк)^2-(0.5Dвк)^2)
Юзер обязан знать сам, что "объем кольца равен Пи умноженному на толщину кольца умноженному на разницу квадратов внешнего и внутреннего радиусов этого кольца".
Решил попрактиковаться:
"В случае наступления события, описанного в предыдущем пункте настоящей инструкции и одновременно с этим состояния из пункта 15.6.3.а, необходимо осуществить выполнение следующих обязательных действий:...."
"Используя перечисленные здесь принципы, вы неизбежно сделаете документацию вашего продукта совершенной. Совершенно бесполезной."
Дак всё-таки, это Первоапрельская шутка или призыв к действию?))) сейчас сложно определиться...
ПС: Я бы ещё предложил таблички текстом писать... желательно, каждую ячейку отдельно описывать😇
Я бы еще к этому гайду добавил пару особо важных пунктов:
Ни в коем случае не используйте пунктуацию. Зачем тратить время и место под знаки препинания
Забудьте про форматирование текста. Пусть информация будет в едином потоке
Не разделяйте документацию на атомарные операции. Пишите все сразу в одном документе Создание\Изменение\Удаление
Оглавление - лишнее искушение. Так у читателя появится возможность ориентироваться в тексте. А это влечет за собой пропуск информации и переход сразу к нужному блоку - мы ведь этого не хотим
Если это документация процесса - пишите только словами, ни к чему утруждать себя диаграммами. Мы ведь не рисовать сюда пришли
Старайтесь не использовать абзацы. И по возможности объединяйте несколько предложений в одно
Не скупитесь на табуляцию при переходе к следующему пункту. Лесенка в тексте добавит игривого настроения для читателя
Как создать худшую техническую документацию