style: Some ideas on General Style


Previous by date: 10 Apr 2002 00:19:24 -0000 Re: DocBook markup & misc help, John R. Daily
Next by date: 10 Apr 2002 00:19:24 -0000 Re: DocBook markup & misc help, John R. Daily
Previous in thread:
Next in thread: 10 Apr 2002 00:19:24 -0000 Some ideas on General Style, Tabatha Persad

Subject: Some ideas on General Style
From: "Tabatha Persad" ####@####.####
Date: 10 Apr 2002 00:19:24 -0000
Message-Id: <061c01c1e025$c1bfaa60$0928a8c0@voodoochild>

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

Previous by date: 10 Apr 2002 00:19:24 -0000 Re: DocBook markup & misc help, John R. Daily
Next by date: 10 Apr 2002 00:19:24 -0000 Re: DocBook markup & misc help, John R. Daily
Previous in thread:
Next in thread: 10 Apr 2002 00:19:24 -0000 Some ideas on General Style, Tabatha Persad


  ©The Linux Documentation Project, 2014. Listserver maintained by dr Serge Victor on ibiblio.org servers. See current spam statz.