http://qs1969.pair.com?node_id=851681


in reply to Introduction to Technical Writing/Documentation

The basic principle of technical writing is simple: Tell them what you're going to tell them. Tell them. Then, tell them what you've told them.

What utter rot! This is a meme invented and perpectuated by training companies, to stretch 2 days of material into a 5 day course and so double, or more, their revenue! It's a good way to improve the "feel-the-width" metric of a book also.


Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
"Science is about questioning the status quo. Questioning authority".
In the absence of evidence, opinion is indistinguishable from prejudice.

Replies are listed 'Best First'.
Re^2: Introduction to Technical Writing/Documentation
by chromatic (Archbishop) on Jul 13, 2011 at 07:30 UTC
    What utter rot!

    Agreed, though it's a failure of technical writing which slavishly copies the format of the spoken presentation.

    One important difference between writing and speaking is that the written word does not necessarily follow a linear chronology. In other words, you don't have to repeat yourself to make a point because the reader can re-read.

      the format of the spoken presentation.

      Even in a spoken presentation, repetition is just filler.

      Some sources try to suggest that it is an application of Spaced Repetition, but this is proven wholly false. For spaced repetition to work, the facts have to be concise and discrete, and must be repeated verbatim. There has also been research that suggests that the timing of repetitions is an important factor in the benefit of repetition, and that the length of the average presentation is simply too short to usefully achieve the benefit of 3 repetitions; even if those repetitions were correctly structured and verbatim.

      With the 'tell'em what you're gonna tell'em; then tell'em; then tell'em whaty've told'em.' meme, the pre & post summaries lack any useful details, so fail to serve as useful reinforcement. Indeed, it has been shown that the preamble serves to cause many of the audience to reach pre-conclusions about the usefulness of all or parts of the session; and/or start anticipating later elements of the talk thereby distracting them from digesting earlier parts that they've pre-concluded to be unimportant.

      There is some merit in summarising a previous dependant session -- "Last time we explored how X led to Y; now we'll see how that helps us to achieve Z" -- but in all cases, written handouts are far more useful than filler summaries, because:

      you don't have to repeat yourself to make a point because the reader can re-read.

      It also leaves more time for looking at some of those details that are traditionally skipped because of "lack of time". Or, allows shorter presentations saving the delegates money; or enabling them to attend more sessions.

      There really is very little merit in the "three Ts" beyond padding trainers saleries and training company coffers.


      Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
      "Science is about questioning the status quo. Questioning authority".
      In the absence of evidence, opinion is indistinguishable from prejudice.
        "Even in a spoken presentation, repetition is just filler..." Not really in spoken word presentations is often used to ensure that the listeners have clearly understood the point or to emphasizes the point been made. And is a very useful tool to gauge the audiences take up of the new information. (Audience Contact - different than Audience participation but has similar goals). I think the point of the meme has been missed by the forum. I took this to mean that a brief over view of what information will be given to prepare the reader for the information or to let the reader know this is the section he needs to read (as he has a question about the software he need answering). the core of the material will be the second time the information will be talked or written about, but this will go into much more detail and fully expand on the solution to the given issue. Then the third time could be a 'this is the question that was asked in the outset and this was the answer that was discussed in the main body of the text'. this lets the reader quickly reference topics and answers to question, he may have. This could be at a later date after the first reading of the documentation. Sorry if this has bumped the topic to the top but i am finding it really helpful.
Re^2: Introduction to Technical Writing/Documentation
by JohnHerald (Initiate) on Jan 20, 2011 at 17:21 UTC
    Actually, the phrase was an old saw in radio copywriting, where you repeated things three times. The formula does have its applications in technical writing, but it would take a stretch to make it fit. For one, if we wrote everything three times, our instructions would balloon accordingly. Yes, we should give the reader a clue as to what we're going to tell them, and it's a good idea to give a summary at the end. But how many people have the time or interest to wade through all that?
      In my opinion, the "Three T" only applies to presentations, the so called, sales pitch. Technical documenting is serious and the most important portion of it is research, research, research...

      "Actually, the phrase was an old saw in radio copywriting, ..." -- JohnHerald. Performance Today is very irritating that way. I wish my radio clock would shut off when non-instrumental audio is encountered during the 2 hour period. ~_#

A reply falls below the community's threshold of quality. You may see it by logging in.