Как писать о вещах, которые зависят друг от друга

Есть два общих подхода, в зависимости от количества деталей, которые вам нужны из концепции «другого».

Если вам не нужно много, напишите о теме А, а когда произойдет первое взаимодействие с Б, добавьте вводное предложение, примечание или сноску (в зависимости от вашего руководства по стилю), описывающую другую концепцию и указывающую на ее основную документация. Например:

Чтобы настроить подписку, сделайте (бла-бла-бла) и укажите URL обратного вызова. (Обратный вызов — это служба, которую вы пишете, которую эта служба будет вызывать с обновленными данными. См. Раздел X.)

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

Это очень распространено в определенных типах проектов. Вы можете попробовать начать с представления древовидной структуры (не обязательно диаграммы) для быстрой общей картины элементов и их взаимозависимости с первого взгляда — вроде вида с воздуха.

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

Дайте нам знать, как вы смотрите на этот вариант.

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

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

Я думаю, что вы, вероятно, должны следовать той же схеме.

1. Введение (дает некоторый контекст)
2. Обзор (различных частей)

А затем продолжайте описывать каждую часть в отдельности.

Единственный способ не иметь прямых ссылок — строить все снизу. Итак, вы начинаете с глоссария, определяя термины, которые собираетесь использовать. В некоторых случаях они могут ссылаться друг на друга, так как все они будут находиться в одной области. Затем вы делаете свои определения - основные процессы, которые задействованы, опять же с некоторыми перекрестными ссылками, если это необходимо. Вы также можете сделать ссылки типа «см. тот человек, который хочет сослаться на это для конкретной потребности, может пройти через это, но его также можно прочитать, игнорируя это.

Надеюсь, к этому моменту вы сможете написать основную часть текста, ссылаясь назад, но не вперед (хотя далее см. также ссылки, которые могут быть полезны — они служат для предоставления ссылок, которым не нужно следовать, чтобы понять).

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

Итак, если вам нужно определить Cyclone Bigit, созданный из Convex Waddle, а выпуклый waddle имеет значение только как прародитель Cycle Bigit, то сначала вы определяете значения — что такое Bigit? Что такое Уоддл? Затем вы определяете Cyclone Bigit, независимо от того, как он генерируется или для чего он нужен. Вы также определяете — независимо от контекста — выпуклую перевалку.

После того, как вы определили их обоих способом, которого недостаточно для их использования, но достаточно, чтобы оценить их потенциальную ссылку, вы можете объяснить, как вы берете и определяете Waddle и делаете из него свой Bigit. Будем надеяться, что кто-то, кто прочитает его полностью, будет постепенно понимать весь процесс и поймет, что нужно к концу.

Всякий раз, когда я нахожусь в этой ситуации, я использую следующее:

• Глоссарии : создание глоссария избавляет меня от раздувания документа подробными пояснениями по «основным вещам». Вместо этого я даю объяснение в 1 предложении, достаточно полезное для остального контекста. Этот лайнер приходит ко мне после того, как я написал глоссарий и несколько раз переписал его.
• Метафоры : если что-то сложно объяснить целевой аудитории, иногда достаточно дополнительного объяснения. Это хорошо работает, когда метафора заменяет другие понятия, кроме центрального, на котором я пытаюсь сосредоточиться.
• Перекрестные ссылки : иногда вам просто нужно объяснить всю махинацию, а лучше сделать это по одному и предоставить ссылку/ссылку на другой раздел (например, «см. страницу X», «прочитать раздел Y»). Аналогично тому, когда приходится использовать глоссарии, но одной записи в глоссарии будет недостаточно.

Я использую LaTeX, и делать глоссарии и делать перекрестные ссылки очень просто.