В последнее время мне приходится очень много работать с различными текстами, как своими, так и чужими. Поэтому я хотел бы поделиться с вами некоторыми наблюдениями по поводу того, на что следует обращать внимание при написании текстов целью которых ставится что-либо последовательно объяснять другим людям, преимущественно мало ознакомленными с предметом повествования. Примерами таких текстов могут выступать различные руководства, наши драгоценные тикеты, в которых мы конечно же не забываем грамотно и лаконично описывать шаги для воспроизведения проблемы и даже задокументированные тестовые случаи.

Итак, включая режим капитана Очевидности, я натягиваю простынь на плечи как плащ, трусы поверх шорт и, вытянув одну руку перед собой, лечу в густую массу суровых людей с техническим образованием, дабы поучить немного их всех жизни.

Лирическое отступление: у меня сегодня была какая-то странная проблема с подбором КДПВ, так что пусть ею будет вот такой комикс:

Вместо введения

Далее ваш текст будет называться материалом, а человек проходящий описываемые в нём действия — читателем. Только предупреждаю: казалось бы где я, а где умение писать хорошие тексты… Так что весь нижеизложенный пост можно считать пятничным набросом, ориентированным прежде всего на людей вовлеченных в процессы тестирования.

Основные моменты на которые стоит обратить внимание

Обозначение проблематики

Введение с явным обозначением проблематики, которую должен решать данный материал, с обозначением состояния на начальном этапе и обозначением состояния на момент завершения читателем действий описанных в материале. В случае с тикетом это — обязательное описание ожидаемого поведения программного обеспечения и фактического. По возможности должна быть отсылка на источник с описанием корректного поведения. Если в качестве ожидаемого поведения обозначается чувство прекрасного самого автора, то следует подкрепить его уверенной аргументацией, а ещё лучше — предварительно согласовать свое мнение с людьми ответственными за требования к проекту.

Чёткая последовательность описываемых действий

Читатель вашего текста точно должен знать какое действие следует (или предшествует) текущему, чтобы при возникновении каких-либо несоответствий между описываемым вами и получаемым по факту, он в кратчайший срок мог локализовать проблему. Любое получаемое читателем состояние должно чётко отслеживаться по тексту. По возможности шаги действий стоит пронумеровать, так при возникновении каких-либо проблем к вам смогут обратиться с точным указанием шага на котором что-то пошло не так.

Однозначность

Любое описанное действие не должно допускать двусмысленного толкования. Никаких описаний своих чувств и эмоций в тексте быть не должно. Использование читателем интуиции и телепатии для достижения обозначенного вами результата неприемлемо. Никаких текстов из разряда "берём произвольное значение в интервале от N до N + 100" — только точные значения входных и выходных значений используемых в примерах (особенно актуально для тестовых случаев).

Понятная терминология и недопустимость переусложнения

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

Скриншоты

Скриншоты не должны служить иллюстрацией ситуации "в жизни так бывает", а должны указывать что-то такое, что достаточно проблематично описать словами. Например, расположение какого-либо элемента в сложном интерфейсе или состояние интерфейса после каких-либо выполненных действий. Рамочки и стрелочки для привлечения внимания к конкретным областям изображения — это наши лучше друзья.

Лаконичный заголовок

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

Вместо послесловия к данному хабропосту

В качестве послесловия стоит, пожалуй, отметить, что все описанные действия я сам не всегда исполняю, ведь кому приятно читать сухой текст… :) Но прежде чем играть словами, дабы не дать скучать коллегам в процессе чтения вашего текста, научитесь всё-таки писать его правильно и понятно, чтобы читатель прежде всего быстро и эффективно достигал цели к которой его ведёт ваш текст.