TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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-
