“The trouble is that I’ve really been struggling to get my head around it and I was finding it very hard to write the descriptions for each conceptual area.”

I run into the same problem from time to time. Using conditional text or conditional tags helps me keep track of that content when using a tool like MadCap Flare or RH.

In fact, I’m trying to figure out an easy way to do conditional tagging on audio for podcast and/or full audio for eLearning presentations. I think the best practice I’ve found for that is over on Articulate’s blog where they recommend using a Notes tab listed as ‘Transcript’.

– Charles

I also would like to emphasize the disconnect between problem and solution, symptom and cure that I find quite common. As you say, your document somehow didn’t work, but the problem (as I understand) was not the actual writing or the structure, but a poorly defined audience. At other times, it may be a poorly defined purpose that makes documentation difficult to write or maintain.