Хабрахабр

Как сделать так, чтобы вашу статью или документацию поняли быстро и точно

Не только содержание, но и структура текста должна быть осмысленна.

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

  • Заголовок
  • Суть статьи
    На основе этих нескольких предложений вместе с заголовком читатель должен понять, интересно ли ему читать эту статью дальше.
  • Краткое изложение
    Здесь в максимально сжатом виде, тезисно, но с необходимой точностью и полнотой должна быть отражена суть данной статьи — от нескольких предложений до нескольких страниц. Кому-то, кто глубоко в теме этого может быть достаточно для понимания всей статьи. Но в любом случае читателю полезно представлять в самом общем виде, о чем эта статья, и какие выводы он получит в конце.
  • Логика статьи
    Если статья длинная, содержит много разделов и сложную логику, то эта глава может быть также полезной. По сути это расширенное оглавление. Здесь кратко, на одной-двух страничках, излагается логика рассуждения, сухо, без деталей. Опять-таки, кому-то этого будет достаточно для того, чтобы все понять. Если сложно, то читатель может это пропустить (как оглавление) и читать дальше.
  • Упрощенное изложение
    Если статья достаточно сложная, то многим было бы удобно сначала понять концептуально, что же хочет сказать автор. Поэтому неплохо сначала изложить все так, как если бы вы рассказывали студентам, упуская сложные доказательства, и, возможно, не столь формальным и строгим языком. Для очень многих такой уровень изложения может быть достаточным, и они остановятся здесь.
  • Строгое изложение
    Здесь строго профессиональное изложение.

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

Мне приходится читать много технической документации. На мой взгляд, общепринятая организация текста неудобна. У меня нет времени (да и желания) наслаждаться последовательным развитием сюжета и красотою слога, это не «Война и Мир», мне нужна лишь информация и чем быстрее, тем лучше. Поэтому в случае новой и сложной темы мне приходится сначала несколько раз сканировать текст в поисках смыслов, выводов и логики, и лишь потом я могу адекватно его воспринимать. То есть фактически я следую изложенному подходу, но в очень неудобной и затратной с точки зрения времени манере, и для меня было бы намного удобней, если бы информация сразу была бы организована соответствующим образом.

Показать больше

Похожие публикации

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *

Кнопка «Наверх»