How to write about things which depend on each other

Question

I am writing a technical documentation about a product. Now problem is there are many interrelated and interdependent concepts. I am just confused how to put them in order. I mean if I talk about first concept, it needs a little understanding of second topic and if I talk about second topic, it needs the understanding of first.

Answer 1

There are two general approaches, depending on the amount of detail you need from the "other" concept.

If you don't need a lot, write about subject A, and when the first interaction with B hits add a parenthetical sentence, call-out note, or footnote (depending on your style guide) describing the other concept and pointing to its main documentation. For exmaple:

To configure a subscription, do (blah blah blah) and specify the callback URL. (A callback is a service you write that this service will call with updated data. See Section X.)

If the topics or their inter-connections are more complicated, the other approach is to write a brief overview that introduces all the concepts. Think of this as breadth-first documentation. The overview should point to the more-detailed documentation on each topic.

Answer 2

This is very common in certain types of projects. You can try beginning with presenting a tree structure (not necessarily a diagram) for a quick overall picture of the elements and their interdependence at a glance -- an aerial view, kind of.

Just remember to follow the same relationship logic in setting out the individual elements in the main discussion. Think of it as presenting a table of contents first and then the chapters in that same order -- only here the TOC is non-linear.

Do let us know how you look at this option.

Answer 3

I think this is a common situation. Most of the systems have different parts that interact with one another, and with the external word.

The best presentations / documentations I have seen all start by first describing the environment in which the system evolves, with a high-level overview of the system itself. Then they quickly present one or two common uses and how they are dealt with.

I think you should probably follow the same pattern.

1. Introduction (gives some context)
2. Overview (of the different parts)

And then go on describing each part individually.

Answer 4

The only way of not having forward references is to build up everything from the bottom. So you start with a glossary, defining the terms you are going to use. In some cases, these can cross reference to each other, as they will all be in the same area. Then you do your definitions - the basic processes that are involved, again with some cross reference if needed. You can also do "see also" type references to later in the manual, so referring in the definition of a wizzlet process, you can say "for details on how to initiate and configure a wizzlet process, see section 26 below ). This means that peple who want to refer to this for a specific need can follow these through, but it can also be read ignoring this.

Hopefully, by this point, you will be able to write the main bulk of the text, referring back but not forward ( although further see also references might be useful - these are to provide links that are not necessary to follow to understand ).

In your specific case, you would define the principles behind topic 1 and topic 2, with possible cross references if necessary, although if you can avoid them, even better. The detailed interaction of these two is dealt with in the main text.

So, if you need a define Cyclone Bigit, which is created from a Convex Waddle, and the convex waddle only has a meaning as the progenitor of a Cycle Bigit, then you define the meanings first - what is a Bigit? What is a Waddle? Then you define the Cyclone Bigit, irrespective of how it is generated, or what it is for. You also define - irrespective of context - the Convex Waddle.

Once you have these both defined, in a way that is insufficient to use them, but sufficient to appreciate their potential reference, you can explain how you take and define a Waddle and make your Bigit out of it. Hopefully, someone reading it all through will have their understanding taken slowly through the whole process, and grasp what is needed by the end.

Answer 5

Whenever I'm in this situation I leverage the following:

• Glossaries: Doing a glossary saves me from bloating a document with detailed explanations on "basic stuff". I instead give a 1 sentence explanation useful enough for the rest of the context. This one liner comes to me after writing the glossary entry and rewriting it several times after.
• Metaphors: If one thing is to hard to explain to a target audience, sometimes a supplementary explanation will just do. This works well when the metaphor is replacing other concepts than the central one I'm trying to focus on.
• Cross-referencing: Sometimes you just have to explain the whole shenanigan, but rather do it one at a time and provide a link/reference to another section (i.e. "see page X", "read section Y"). Similar to when having to use glossaries, but a glossary entry alone wont be enough.

I use LaTeX and doing Glossaries and cross-referencing is easy as cake.