style: Some ideas on General Style
Subject:
Some ideas on General Style
From:
"Tabatha Persad" ####@####.####
Date:
10 Apr 2002 21:30:29 -0000
Message-Id: <008401c1e0d7$521c6e70$0928a8c0@voodoochild>
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
