wkitty42 wrote in Sat Mar 07, 2015 9:35 pm:for me, it isn't that they are pathetic... it is that some information is left out... in one of my other lives, i'm a member of a technical documentation team... others on that team just do not understand the need of using plain layman's terms and explaining the most basic of concepts... they don't understand this because they assume that only developers are going to be interested in the documents... what they forget is that the laymen users of the technology want to learn how it works to they try to read those same docs and they end up in the same position as the OP, myself and others who are trying to understand and are at least asking questions instead of giving up because it is too hard to understand...
One of the principles to consider when writing technical documentation is to 'write out the obvious'. When writing technical documentation you at least have spent a lot of time on trial and error, reading in on a subject and/or developing a feature yourself. What is too obvious to write for someone can be the missing piece in the puzzle for someone else. It is surprising how often that have been the case when I am trying to learn something in FlightGear (and other contexts as well).
In addition to that there is of course all those other things one can do as an article writer to help the readers cognitive processes, for example:
- Beginning with a brief overview*
- Briefly explain terms on their first occurrence in an article
- Having a good section and subsection structure
- Not repeating oneself or having too many similar visual cues
- Possibly ending with a conclusion
- Referring to related content (for example articles and/or categories)