Beefy Boxes and Bandwidth Generously Provided by pair Networks
Keep It Simple, Stupid
 
PerlMonks  

Re^2: Introduction to Technical Writing/Documentation

by chromatic (Archbishop)
on Jul 13, 2011 at 07:30 UTC ( #914070=note: print w/ replies, xml ) Need Help??


in reply to Re: Introduction to Technical Writing/Documentation
in thread Introduction to Technical Writing/Documentation

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.


Comment on Re^2: Introduction to Technical Writing/Documentation
Re^3: Introduction to Technical Writing/Documentation
by BrowserUk (Pope) on Jul 13, 2011 at 08:21 UTC
    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.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://914070]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others pondering the Monastery: (8)
As of 2014-07-11 22:10 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    When choosing user names for websites, I prefer to use:








    Results (235 votes), past polls