discuss: Some ideas on General Style
Subject:
Re: Some ideas on General Style
From:
David Lawyer ####@####.####
Date:
10 Apr 2002 20:55:13 -0000
Message-Id: <20020410135459.A593@lafn.org>
On Tue, Apr 09, 2002 at 05:22:09PM -0700, Tabatha Persad wrote:
>
[snip]
> I have been thinking more about general style though and came up with
> some ideas. I'll just put these out there for consideration in
> whatever format is most appropriate, but some basics:
>
> Document Structure:
>
> To expand a little on Greg Turner's description of document structure,
> in addition to a logical, smooth transition from one topic to the
> next, I have noticed an overall similarity in the structure of most
> documents. Online documents differ from printed documents in the
> order some things are displayed, such as copyright, credits etc.
> These are just the common items I have encountered; the order may
> vary:
> 1. Credits/Copyrights/Contributors/Acknowledgements (terminology varies)
> 2. Table of Contents
> 3. Introduction/Forward/Scope/Audience
> 4. Main body of document, the HOWTO part (here is where I see Greg's structure)
> 5. Resources/Links/FAQ/Bibliographies
> 6. Appendices/Glossaries/Indices
Why not put 1. into 3. Then one can check the table of contents for
this info (Credits, Copyrights, Contributors, etc.). Also included should
be "what's new in this version" (or recent versions) so that people who
have read old versions don't need to read over the same stuff. Also,
there should be a request for feedback where readers are invited to make
suggestions for improvement and point out typos, lack of clarity, etc.
For "Links", etc. it's best to put them right where the topic is being
discussed. They can also go in a separate section such as suggested
above.
>
> Style Don'ts:
>
> - Humor and emotion symbols that cannot be accurately translated
If the humor can be translated, then it's OK but it shouldn't be
overdone.
> - Contractions which cannot always be accurately translated
Simple contractions in common use can be accurately translated.
> - Undefined acronyms and abbreviations
If the acronym is well known like PC, MS (M$ ??), or IBM, then it should
be OK not to define it.
> - Personal opinions
If the opinion is well founded, then I think it's OK. When there are
different methods of doing something, the reader would like some advise
as to which one to choose in which situation and that's in part a matter
of opinion.
> - Sexist or gender specific language
I think it's up to the author what s/he should do. Some say that there
is no such word as "s/he". For many years it was understood that "he"
included "she", today some people alternate between "she" and "he" or
even use all "she". I don't think this is sexist.
> - Culture specific slang (words that other countries might not understand)
Agreed
> - Maybe if's (maybe if so-and-so develops such-and-such then we can do
> this one day)
Documents can propose what developers need to develop to improve things.
So something like the above is sometimes desirable.
> - A condescending tone
Agreed
David Lawyer
