Re: Better language to intorduce documents

Sesquipedalian Sam <sesquipod@xxxxxxxxxxxxx> writes:

From time to time I have the need to write program or product
specifications or descriptions. I am not a writer, so I just do the
best I can.

There is one part where I always seem to have trouble. I seem to be in
a bit of a rut with the very first paragraph. I find myself starting
every document with something like

This document describes the XYZ product...

I feel compelled to start out by describing the purpose of the
document. Sometimes this is just one sentence. Sometimes it's a couple
of paragraphs.

Is there anything wrong with starting every document this way?

Is there a better way to get the document started?

Are there some general principles about introducing a document?

I'd apprectiate any suggestions.

The purpose of this response is to reply to your posting. In it I will
describe my reactions on what you have written and produce a response to
it, describing my thoughts and the processes behind them.

It's just woffle!

I have to say I hate those - they form part of what I call
"contractorese" - when you are paying someone to build you something,
or to produce a report on something, it always ends up with pages of
verbiage, and I tend to treat sentences like this.

If I am reading a paper called "How to use the XYZ Confabulator" I
/know/ that "The purpose of this document is to describe how to use the
XYZ Confabulator". Cut it out, and the world will be a better place.

To summarise, I have considered the purpose of the sort of opening
structure the original poster proposed and have given my reactions. You
will note that neither the opening nor closing paragraphs give any
information at all - they are not actual summaries or introductions,
they are simply many words strung together with no actual meaningful
content whatsoever.
--
Online waterways route planner: http://canalplan.org.uk
development version: http://canalplan.eu
.

Relevant Pages