Re: A tech editor seeks advice on which style guide to adopt

Subject: Re: A tech editor seeks advice on which style guide to adopt
From: Patricia Egan <capdev -dot- communications -at- gmail -dot- com>
To: praneeta p <praneeta_paradkar -at- yahoo -dot- com>
Date: Fri, 25 Sep 2009 09:34:31 -0700

The fate of Sun's READ ME FIRST! is a third edition, to be published in
November 2009.
http://ekschi.com/technology/2009/09/01/new-sun-press-title-read-me-first-a-style-guide-for-the-computer-industry-third-edition/

Pat

On Thu, Sep 24, 2009 at 4:31 AM, praneeta p <praneeta_paradkar -at- yahoo -dot- com>wrote:

> Hi All,
>
> So here's a Style Guide comparison matrix that I developed after having
> read numerous e-mails, forums, and counsel from ex-colleagues. I also take
> this opportunity to thank all those who wrote back on the topic. Your inputs
> were valuable. Thanks again.
>
> Needless to say: my verdict is in favor of Sun's Read Me First. Having
> undergone so much pain to come to this decision, I have been told that
> Oracle is buying out Sun. What, pray tell me, is the fate of the Sun's Style
> Guide???
>
>
> Style Guide Analysis
>
> Parameters:
> 1. Depth of topics
> 2. Breadth of topics
> 3. Special treatment of topics of interest – such as screen elements,
> writing for a global audience.
> 4. Examples & rationale
> 5. Tone and flexibility (degree of specificity)
> 6. Ease of reference
> 7. Availability
>
>
>
>
>
>
>
> Style Guide
>
> Strengths
>
> Weaknesses
>
>
>
> MSTP
>
> 1. Most topics are detailed. Scores a 4/5 on depth and breadth
> (flip-side).
> 2. Examples are good with correct and incorrect usage clearly
> delineated.
> 3. Screen terminology treatment is detailed.
> 4. MS products are used world-wide and most people are familiar with
> their word usage, terminology, and documentation style (which does not in
> any way mean that MSTP is the absolute in the computer world.) But then
> users are happy!
> 5. Up-side to being inflexible is lesser ambiguity and lesser
> debates.
> 6. Online version relatively easier to reference.
>
>
> 1. Rationale at times is ambiguous.
> 2. Tone is many times dictatorial than suggestive (up-side).
> 3. Examples, at times, cannot be extrapolated to our situation.
> 4. Heavy focus on usage dictionary and less on writing guidelines.
> 5. Punctuation section is too detailed for end-user documentation.
> 6. Heavily centered on MS Windows (obviously!), but there is an
> up-side to this (see strengths).
> 7. Only purchased copies available. Free versions are outdated.
> 8. Flip-side of being too detailed is that the conventions are
> sometimes difficult to remember or recollect.
> 9. No guidelines on constructing a glossary or scripting glossary
> terms.
> 10. Printed version – difficult to reference.
>
>
>
> Sun’s Read Me First
>
>
> Rationale is crisp.
> Size is manageable and compact.
> Healthy dose of writing style, mechanics, constructing sentences and
> mechanics without overkill.
> Tone provides leeway and is flexible.
> Some sections have received outstanding treatment:
>
> Common redundancies and alternatives
> GUI Verbs
> Questionable terms and their alternatives.
>
> Better than MSTP for client server as well as web-based applications.
> 7. Section on Punctuation is nice and crisp.
> 8. Chapter on Glossary and Indexing are detailed.
> 9. Chapter on Writing for an International Audience has concrete dos
> and don’ts and examples.
> 10. Third edition has newer sections on:
>
> Anthropomorphisms to Avoid
> Idioms and Colloquialisms to Avoid
> Phrasal Verbs to Avoid and Their Alternatives
>
> The fourth edition has improved chapters on:
>
> Writing For An International Audience
> Writing about GUIs
> Working with Technical Illustrations
> Guidelines for easing translation of documents.
>
>
>
> Scores 3/5 for depth and breadth.
> Screen terminology has not been discussed in detail (the 4th edition
> promises to take care of this).
> Less detailed on usage dictionary.
>
>
>
> IBM Style Guide
>
> Compact, but at the cost of useful discussion.
>
> Free!!!
>
> Heavily based on the Chicago manual of Style.
>
>
> Apple Style Guide
>
> More or less similar to IBM’s.
>
> Heavily based on the Chicago manual of Style.
>
>
> Chicago Manual of Style
>
> Considered a bible by American publishing houses
>
> Is a general style guide used in mainstream publishing, not for
> software/computer terminology.
> Example: It directs you to put periods and commas inside quotation marks.
> However, if you use quotation marks to enclose commands that users enter on
> their computer keyboards, that rule would create problems: normally, the
> user should not end a keyboard command with a period or comma even though
> the format seems to require it:
> Type "delete myfile.doc." > Type "delete myfile.doc".
>
>
>
> The AP Stylebook
>
> None (as compared to Chicago or others). At par with CMS though less
> detailed.
>
> Contradicts some well known tenets such as the serial comma. Sun & MSTP
> both recommend a serial comma, AP advises against it.
> Good for academic and trade journals, not relevant to software/computers.
>
> --- On Wed, 23/9/09, praneeta p <praneeta_paradkar -at- yahoo -dot- com> wrote:
>
>
> From: praneeta p <praneeta_paradkar -at- yahoo -dot- com>
> Subject: A tech editor seeks advice on which style guide to adopt
> To: TECHWR-L -at- lists -dot- techwr-l -dot- com
> Date: Wednesday, 23 September, 2009, 2:59 PM
>
>
>
>
>
>
>
> Hi All,
>
> Recently, in one of our doc team meetings, my manager asked me to come to a
> formal decision on which style guide we should adopt as the bible for our
> team. And as it goes with managers, I have to justify my decision.
>
> So far, the writers have been using MSTP (Microsoft Style for Technical
> Publications) for two reasons:
>
> 1. It is easily available.
> 2. and free.
>
> I rather like Sun's Read Me First. The rationale appeals to me. The
> recommendations in their sound like recommendations and are less dictatorial
> than the MSTP.
>
> I would like to know which style guide would be best for web-based
> applications?
>
> Is MSTP really only for Windows-based apps or can it be adopted for
> web-based apps too?
>
> Which style guide (Sun's or MSTP) is likely to be adopted easily by the
> writers? That is not to say that I will take the path of least resistance if
> one or the other wins in merit versus ease of adoption.
>
> Kindly advise.
>
> Best always,
>
> Praneeta Paradkar
>
>
>
>
> Yahoo! India has a new look. Take a sneak peek.
>
> From: praneeta p <praneeta_paradkar -at- yahoo -dot- com>
> Subject: A tech editor seeks advice on which style guide to adopt
> To: TECHWR-L -at- lists -dot- techwr-l -dot- com
> Date: Wednesday, 23 September, 2009, 2:59 PM
>
>
>
>
>
>
>
> Hi All,
>
> Recently, in one of our doc team meetings, my manager asked me to come to a
> formal decision on which style guide we should adopt as the bible for our
> team. And as it goes with managers, I have to justify my decision.
>
> So far, the writers have been using MSTP (Microsoft Style for Technical
> Publications) for two reasons:
>
> 1. It is easily available.
> 2. and free.
>
> I rather like Sun's Read Me First. The rationale appeals to me. The
> recommendations in their sound like recommendations and are less dictatorial
> than the MSTP.
>
> I would like to know which style guide would be best for web-based
> applications?
>
> Is MSTP really only for Windows-based apps or can it be adopted for
> web-based apps too?
>
> Which style guide (Sun's or MSTP) is likely to be adopted easily by the
> writers? That is not to say that I will take the path of least resistance if
> one or the other wins in merit versus ease of adoption.
>
> Kindly advise.
>
> Best always,
>
> Praneeta Paradkar
>
>
>
>
> Yahoo! India has a new look. Take a sneak peek.
>
>
> Add whatever you love to the Yahoo! India homepage. Try now!
> http://in.yahoo.com/trynew
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Free Software Documentation Project Web Cast: Covers developing Table of
> Contents, Context IDs, and Index, as well as Doc-To-Help
> 2009 tips, tricks, and best practices.
> http://www.doctohelp.com/SuperPages/Webcasts/
>
> Help & Manual 5: The complete help authoring tool for individual
> authors and teams. Professional power, intuitive interface. Write
> once, publish to 8 formats. Multi-user authoring and version control!
> http://www.helpandmanual.com/
>
> ---
> You are currently subscribed to TECHWR-L as
> capdev -dot- communications -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
> or visit
> http://lists.techwr-l.com/mailman/options/techwr-l/capdev.communications%40gmail.com
>
>
> To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwr-l.com/ for more resources and info.
>
> Please move off-topic discussions to the Chat list, at:
> http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat
>
>


--
Patricia Egan
P. O. Box 194391
San Francisco, CA 94119-4391
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices.
http://www.doctohelp.com/SuperPages/Webcasts/

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


References:
Re: A tech editor seeks advice on which style guide to adopt: From: praneeta p

Previous by Author: Re: A tech editor seeks advice on which style guide to adopt
Next by Author: RE: Alternatives to AuthorIT
Previous by Thread: Re: A tech editor seeks advice on which style guide to adopt
Next by Thread: Re: A tech editor seeks advice on which style guide to adopt


What this post helpful? Share it with friends and colleagues:


Sponsored Ads