Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

How to write about things which depend on each other

+0
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/4825. It is licensed under CC BY-SA 3.0.

0 comment threads

4 answers

+1
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

This post was sourced from https://writers.stackexchange.com/a/4834. It is licensed under CC BY-SA 3.0.

0 comment threads

+1
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+1
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

This post was sourced from https://writers.stackexchange.com/a/4826. It is licensed under CC BY-SA 3.0.

0 comment threads

+1
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

This post was sourced from https://writers.stackexchange.com/a/5759. It is licensed under CC BY-SA 3.0.

0 comment threads

Sign up to answer this question »