Это про внутреннюю документацию. Не наружу. Для своих: для людей, с которыми вы делаете одну работу и которые потом пойдут по этому тексту работать. Именно тут часто пишут мимо них. Страница должна выглядеть серьёзно. Чтобы было видно, что автор разбирается. Канцелярит, громоздкие формулировки, тон «так принято в нормальных компаниях». Документ выглядит солидным и важным, но читать его не хочется.

Менеджеры, это вам. Не команде, которая «не дочитала». Если по требованиям нельзя понять, что делать, это не слабый разработчик. Это вы закрыли задачу «написать документацию».

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

Вместо своей головы

Документацию сразу страшно сесть и написать самому. Если в тему не вник, то покажешься тупым. Сложными словами закрывают не информацию для другого человека, а то, что сами не поняли. Поэтому вместо смысла остаются термины, а непонятный текст кажется глубоким. Туда же сейчас прячут глупость и слабое знание темы: текст нейронки вместо своей головы. Одним куском или по частям, без разницы: если текст просто сгенерирован, без своей мысли, это уже нейрослоп.

Я собрал бизнес-требования именно так. Первая версия была нейрохрючевом. По образцам из интернета, громоздко, канцелярски. С виду по-деловому и почти солидно. Рядовой человек на проекте ничего не понял. Засыпал с первых строк. Документ можно было показать. Понять его нельзя было.

Если не можешь написать понятно, скорее всего сам не до конца понял. Или нейрослопил: отдал гладкий текст нейронки и сам его не объяснишь. Должность и кнопка генерации тут ни при чём. Решает другое: можешь ли пересказать абзац своими словами.

Если не поняли документ, часто виноват не тот, кто читал. Виноват тот, кто написал. Он не донёс. Сделал текст, чтобы он был и выглядел как надо. Не чтобы его поняли.

Сделал, чтобы поняли

Я остановился и разрезал требования на две части. Первая короткая, обычными словами: про что эта фича и чего мы от неё хотим. Вторая уже с техническими подробностями. Формулировки тоже понятные. Рядом схемы и рисунки, чтобы было видно, а не надо было разгадывать.

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

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

#ПишиПонятно