style: Thread: Some ideas on General Style

While I've been reading through documentation on writing style, I wanted to comment on some of the things that I've observed so far, which could be considered for inclusion in the guide.

With respect to technical style, Alexander Bartolich brought up an interesting point at ####@####.#### He states how it can be frustrating to read through the majority of a document only to find out the author was only talking about specific versions of applications or kernels etc.  This might be something that needs to be addressed, no?  I don't know the right terminology for it, but basically stating a "requirements" or a basis that the author started with upfront on the versions used, as well as where to find the versions applicable to the documentation.

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 Contentes
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

Style Don'ts:

- Humor and emoticon symbols that cannot be accurately translated
- Contractions which cannot always be accurately translated
- Undefined acronyms and abbreviations
- Personal opinions
- Sexist or gender specific language
- Culture specific slang (words that other countries might not understand)
- Maybe if's (maybe if so-and-so develops such-and-such then we can do this one day)
- A condescending tone

Style Do's

- Omit unnecessary words
- Use short sentences
- Use short paragraphs, new paragraph for new thought or concept
- Use concrete/explicit examples
- Use consistent vocabulary/terminology
- Spell check using a common resource


Do you think these ideas are too rigid or hard to work with?  Would they be discouraging to editors and authors?  Discussion welcome!

Thanks,
Tabatha

From: "David Lawyer" ####@####.####
> > 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.

I agree.  As mentioned, it really does seem to vary.  In the howto I wrote
for The Linux Counter, I put Revisions before the TOC, and my
feedback/translation info was in my final section, titled "Conclusion",
where I put Copyright, Credits, Contributors.

> 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.

I would agree with that as well.  In my case, I just used cross references
to take the user to the Resources section of my howto, but if it's something
they really need to see before proceeding I would definitely want to put the
link where the topic is being discussed.

> > 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

Yes, all of these things are subject to interpretation and variation.  As
previously mentioned, the style guide doesn't want to be so rigid that the
author is second guessing himself so much that he can no longer write.  The
"don'ts" I will leave up to the powers that be... I have a tendency to
follow these basic guidelines and do not find them hampering my writing, so
thought I'd pass it on.

Thanks!
Tabatha

On Tue, 9 Apr 2002, Tabatha Persad wrote:

> Style Don'ts:
 ...
> - Sexist or gender specific language

This is a culturally-dependent concept, affecting mainly N. Americans.
Personally I'm proud of my (British) linguistic heritage; have an
excellent reading background in a variety of texts written in English
over the past six centuries, and don't suffer from any sort of semantic
constipation in the language.
My personal attitude is to stick to historic usage (known and
recognised), and eschew late 20th C. fads, experimentation and
uproarious attempts at social engineering.  (see Australian Government
Manual of Style recommendations on lexical items such as 'manhole
cover'.)

> - A condescending tone

Again, this is culture-dependent.  (See paragraph above.)
British public school education does not necessarily equip one to
communicate effectively with the average Australian outback ocker.
What is considered condescending for one is not for the other.
Etc.

> - Spell check using a common resource

Problematic.  No way am I ever going to change my British editing
workstation defaults to accept N. American spelling and punctuation
habits (or default American page print sizes); any more than others
are going to accept British or European norms in the same areas.


All in all, I would suggest that until one flavour of English becomes
acceptable as a global 'lingua anglica', we all continue to use our own
idiolectal versions; and learn to interpret the other varieties we
encounter.

And of course, whatever its origins, good writing will always be read
and reproduced.  Bad writing will sink without trace.

Martin
-- 
Martin Wheeler ####@####.#### gpg key 01269BEB @ the.earth.li

On Sat, Apr 13, 2002 at 02:28:43PM +0000, Martin WHEELER wrote:
> On Tue, 9 Apr 2002, Tabatha Persad wrote:
> 
> > Style Don'ts:
>  ...


> 
> All in all, I would suggest that until one flavour of English becomes
> acceptable as a global 'lingua anglica', we all continue to use our own
                                 ^^^^^^^
Anglian chauvinist.


:-)


-- 

Charles Curley                  /"\    ASCII Ribbon Campaign
Looking for fine software       \ /    Respect for open standards
and/or writing?                  X     No HTML/RTF in email
http://w3.trib.com/~ccurley     / \    No M$ Word docs in email