Beta
×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Book Review: Microsoft Manual of Style

samzenpus posted more than 2 years ago | from the read-all-about-it dept.

Books 110

benrothke writes "The Chicago Manual of Style (CMS), now in its 16th edition, is the de facto style guide for American writers. It deals with aspects of editorial practice, grammar, usage, document preparation and more. It's just one of many style guides for writers. The Microsoft Manual of Style, just released in its 4th edition, attempts to do for the technical writers what the CMS has done for journalists and other writers." Read below for the rest of Ben's review.A style guide or style manual is a set of standards for the writing and design of documents, either for general use or for a specific publication, organization or field. The implementation of a style guide provides uniformity in style and formatting of a document. There are hundreds of different style guides available — from the The Elements of Style by Strunk and White, to the Associated Press Stylebook and Briefing on Media Law and many more.

Microsoft's goal in creating this style manual is about standardizing, clarifying and simplifying the creation of content by providing the latest usage guidelines that apply across the genres of technical communications. The manual has over 1,000 items, so that each author does not have to make the same 1,000 decisions.

Anyone who has read Microsoft documentation knows it has a consistent look, feel and consistency; be it a manual for Visual C#, Forefront or Excel. With that, the Microsoft Manual of Style is an invaluable guide to anyone who wants to better the documentation they write.

For example, many writers incorrectly use words such as less, fewer, and under as synonymous terms. The manual notes that one should use less to refer to a mass amount, value or degree; fewer to refer to a countable measure of items, and not to use under to refer to a quantity or number.

Style guides by their very nature of highly subjective and no one is forced to take accept the Microsoft style as dogma. The authors themselves (note that the book was authored by a group of senior editors and content managers at Microsoft, not a single individual) note that they don't presume to say that the Microsoft way is the only way to write. Rather it is the guidance that they follow and are sharing it with the hope that the decisions they have made for their content professionals will help others promote consistency, clarity and accuracy. With that, they certainly have achieved that goal.

The book is made up of two parts; with part 1 comprised of 11 chapters on general topics.

Chapter 1 is about Microsoft style and voice and has basic suggestions around consistency, precision, sentence structure and more. The chapter also has interesting suggestions on writing bias-free text. It notes that writers should do their best to eliminate bias and to depict diverse individuals from all walks of life in their documentation. It's suggested to avoid terms that may show bias with regards to gender, race, culture, ability, age and more. Some examples are to avoid terms such as chairman, salesman and manpower; and use instead moderator, sales representative or workforce.

The manual also notes that writers should attempt not to stereotype people with disabilities with negative connotations. It suggests that documentation should positively portray people with disabilities. It emphasizes that documentation should not equate people with their disability and to use terms that refer to physical disabilities as nouns, rather than adjectives.

The book takes on a global focus and notes that since Microsoft sells its products and services worldwide, content must be suitable for a worldwide audience. For those writing for a global audience, those sections of the manual should be duly considered.

The manual also cautions authors to avoid too many technical terms and jargon. The danger of inappropriate use of technical terms is that people who don't think of themselves as computer professionals consider technical terms to be a major stumbling block to understanding. The manual suggests whenever possible, to use common English words to get the point across, rather than technical one.

The book provides thousands of suggestions on how to write better documentation, including:
do not use hand signs in documentation — nearly every hand sign is offensive somewhere
do not refer to seasons unless you have no other choice – since summer in the northern hemisphere is winter in the southern hemisphere
spell out names of months – as 3/11/2012 can refer to March 11, 2012 in some places and November 3, 2012 in others
use titles, not honorifics, to describe words such as Mr. or Ms. – not all cultures have an equivalent to some that are common in the United States, such as Ms.

Chapter 6 is on procedures and technical content, and explains that consistent formatting of procedures and other technical content helps users find important information quickly and effectively. In the section on security, the style guide notes not to make statements that convey the impression or promise of absolute security. Instead, the writer should focus on technologies or features that help achieve security; and suggests to be careful when using words such as safe, private, secure, protect,and their synonyms or derivatives. It is best to use qualifiers such as helps or can help with these words.

As noted earlier, the style guide is simply a guide, not an absolute. In the book Eats, Shoots & Leaves: The Zero Tolerance Approach to Punctuation, author Lynne Truss write of terms that are grammatically incorrect, but so embedded into the language, that they are what she terms a lost cause. With that, the style guide has the pervasive use of the term all right, as opposed to alright.

According to dictionary.com, although alright is a common spelling in written dialogue and in other types of informal writing, all right is used in more formal, edited writing. My own preference is that alright is clearer and ultimately more concise. In this guide, I found that Microsoft's preference for all right to be distracting.

Differences aside, part 1 provides vital assistance to any writer that is interested in writing effective content that educates the reader in the clearest manner possible. The book is the collective experience of thousands of writers and their myriad sets of documentation. The book provides page after pages of unique information.

Part 2 is a usage dictionary that is a literal A-Z of technical terms, common words and phrases. The goal of the usage dictionary is to give the reader a predictable experience with the content and to ensure different writers usage a standard usage of the same term. Some interesting suggestions in the usage dictionary are:

access rights – an obsolete term. Use user rights
collaborator – do not use collaborator to describe a worker in a collaborative environment unless you have no other choice as it is a sensitive term in some countries. Specifically, being a collaborator in a third-world country can get one killed.
email – do not use as a verb. Use send instead.
master / slave – do not use as the terminology, although standard in the IT industry, may be insulting to some users. The manual notes that its use is prohibited in a US municipality.
press – differentiate between the terms press, type, enter, and use, and to use press, not depress, hit or strike when pressing a key on the keyboard

Some of the terms suggested are certainly Microsoft centric, such as:
blue screen – they suggest not to use blue screen, either as a noun or a verb to refer to an operating system failure. Use stop or stop error instead
IE – never abbreviate Internet Explorer; always use the full name

Say what you will about Microsoft, but any technical writer who is serious about being a better writer can learn a lot from the writers at Microsoft. Microsoft is serious and passionate about documentation and it is manifest in this style guide.

Microsoft has been criticized for their somewhat lukewarm embrace of open source. With the Microsoft Manual of Style, Microsoft is nearly freely sharing a huge amount of their intellectual capital. At $29 for the paperback and $10 for the Kindle edition, the manual has a windfall of valuable information at a bargain-basement of a price.

This guide is a comprehensive manual for the serious writer of technical documentation, be it a high school student or veteran author. In fact, to describe the guide as comprehensive may be an understatement, as it details nearly every facet of technical writing, including arcane verb uses.

Many authors simply write in an ad-hoc manner. This manual shows that effective writing is a discipline. The more disciplined the writer, the more consistent and better their output. Anyone that wants to be a better writer will undoubtedly find the Microsoft Manual of Style an exceptionally valuable resource.

Ben Rothke is the author of Computer Security: 20 Things Every Employee Should Know.

You can purchase Microsoft Manual of Style from amazon.com. Slashdot welcomes readers' book reviews -- to see your own review here, read the book review guidelines, then visit the submission page.

cancel ×

110 comments

Sorry! There are no comments related to the filter you selected.

MS is taking the Chicago way of pay to play / cut (-1)

Joe_Dragon (2206452) | more than 2 years ago | (#39407451)

MS is taking the Chicago way of pay to play and taking a cut with the windows app store.

$99 year + 30%

Re:MS is taking the Chicago way of pay to play / c (1)

cpu6502 (1960974) | more than 2 years ago | (#39407743)

???
"You can purchase Microsoft Manual of Style from amazon.com."

Re:MS is taking the Chicago way of pay to play / c (0)

Joe_Dragon (2206452) | more than 2 years ago | (#39407755)

not for this book but there windows app store plans are the Chicago way with the pay to play part.

Re:MS is taking the Chicago way of pay to play / c (0)

Anonymous Coward | more than 2 years ago | (#39412337)

So your post is completely off-topic?

Re:MS is taking the Chicago way of pay to play / c (1)

gmhowell (26755) | more than 2 years ago | (#39408727)

I thought the Chicago way was more like: " They pull a knife, you pull a gun. He sends one of yours to the hospital, you send one of his to the morgue. *That's* the *Chicago* way! "

Is it me or... (-1)

Anonymous Coward | more than 2 years ago | (#39407483)

isn't Visual Studio-generated MFC code the most ugly, nonstandard, and unreadable code on the planet?

Re:Is it me or... (1)

X0563511 (793323) | more than 2 years ago | (#39407631)

doesn't that have nothing to do with technical writing?

Also, stop putting your comment in the subject box.

Sorry, I won't do it again (0)

Anonymous Coward | more than 2 years ago | (#39407731)

Also, stop putting your comment in the subject box.

stop posting as AC (0)

Anonymous Coward | more than 2 years ago | (#39408189)

I'm the real AC

And don't change the comment subject line (1)

tehcyder (746570) | more than 2 years ago | (#39412143)

because that's really annoying too.

Man, you're right about that, I hate that (1)

drodal (1285636) | more than 2 years ago | (#39415533)

some people just don't get it.

Re:Is it me or... (-1, Troll)

Grishnakh (216268) | more than 2 years ago | (#39408437)

Style is all about aesthetics, which are important for many reasons, including making information more accessible or making devices easier to use.

Microsoft is the last entity that anyone should be listening to when it comes to matters of style. Just look at the style they have with all their other stuff: their OS is ugly, but their new phone OS and Metro UI are leaps and bounds uglier than anything they've made so far. This is nothing new though; WinXP was famous for its "Fisher-Price" style UI. Or, look at their ad campaigns. Search on YouTube for "Microsoft Songsmith commercial" and see just how bad their marketing style is. Or look up their MSN butterfly ad campaigns.

I can't think of a single place where MS has good or even decent style, for anything. Everything they make is ugly or cheesy. They're the last people you want to listen to for writing technical content. They probably even recommend using Comic Sans font for technical content. I haven't read their manual (nor am I likely to), but if it's actually any good, it's definitely one of those "broken clock is right twice a day" things, because for everything else, their style is just horrid.

Re:Is it me or... (0)

Anonymous Coward | more than 2 years ago | (#39408965)

Saying your screenname aloud is unpleasant to my ears. I can only conclude that you are a poor artist.

Re:Is it me or... (1, Informative)

Grishnakh (216268) | more than 2 years ago | (#39409119)

Depends on what aesthetic you're aiming for. "Grishnakh" is a fine name for an evil orc who fights for the dark lord Sauron, and needs a name that evokes fear and dread in his enemies. If you want to design something fearsome-looking, then Grishnakh would probably be a good being to consult with, but probably not if you're trying to design cute children's toys.

MS, however, has frequently shown that their style is cheesy, even in their allegedly "Professional" operating system GUIs, so looking to them for advice on professional writing doesn't seem like a very good idea. They'd probably be a good place for Fisher-Price to go to design a UI for devices aimed at children, however.

Re:Is it me or... (0)

Anonymous Coward | more than 2 years ago | (#39409283)

Technical writers don't pick the GUI colour scheme. Writing is a different skill than GUI design. I doubt there's a significant correlation between how good a GUI is and how good the technical writing is. Or between either of those and how good or bad an ad campaign is (they hire other people to make those in the first place).

Maybe you took one look at Windows XP and decided you wanted those guys to design your Fisher-Price jumping gym. That's somewhat plausible I guess. What's not plausible is somebody took one look at Windows XP and said "I'm going to get these guys to write the assembly instructions for my Fisher-Price jumping gym". And then confusing those guys with the guys who wrote Halo.

Re:Is it me or... (1)

hairyfeet (841228) | more than 2 years ago | (#39410301)

Win2K was nice, win 7 was nice, XP was Fisher price but easily switched and XP X64 was built like a tank and again easy to skin. if you want to talk fugly though then lets talk metro, the half assed "Its a desktop, its a tablet, its half of one and half the other and neither really works!" which has to be the stupidest damned UI since MS Bob. I mean do you see Apple making iOS the new mac OSX? Nope they are working on making the APPS work on both because hey! That actually makes sense. I swear MSFT and so many of the other UI developers are stuck with the cargo cult mindset [piestar.net] where they THINK they understand a thing but in reality they are just aping the most obvious layer which which just gives you a "kinda sorta but not really" half assed design. And can we find the fucknuts that came up with the bright idea that ALL OSes should be fucking cell phones and throw them under a bus, please?

The sad part is they have a couple of really good products they just don't have a fucking clue what to do with them. they should push back Windows 8 for another 2 years to give Windows 7 time to be adopted by businesses and they should go back to having the consumer and business desktop be two different things. no business is gonna want the social bling bling fucking trainwreck that is Metro as a business OS, they should spin off metro into an OS strictly for ARM and X86 tablets and phones and leave Windows for the desktop. But frankly win 7 is damned good, winPhone 7 is nice, they just don't have a single original thought on what to do with either. in a way it reminds me of the clusterfuck that was HP and WebOS, where you have this really nice thing but a company so lame they couldn't sell porn in a prison.

What's wrong... (0)

Anonymous Coward | more than 2 years ago | (#39409389)

...with that?

what's in a name? (5, Funny)

Bobtree (105901) | more than 2 years ago | (#39407485)

MS may well have written more technical documentation than any other company ever, but when I see this book title, I think of things like "The Pompeii Manual of Architecture" or "The Hindenburg Guide of Dirigibles" or "The Atlantis Treatise on Waterfront Properties."

Re:what's in a name? (0)

Anonymous Coward | more than 2 years ago | (#39407497)

aha that is pretty funny too bad you are going to modded down into oblivion by the m$ astroturfing crowd

Re:what's in a name? (4, Insightful)

parlancex (1322105) | more than 2 years ago | (#39407535)

Say what you will about the quality of the actual products, but Microsoft's technical documentation is actually pretty amazing compared to other vendors (I'm looking at you Cisco). Microsoft's documentation is generally well organized, comprehensive, and the writing style is simple and concise; basically everything you'd want technical writing to be.

Re:what's in a name? (5, Insightful)

Anonymous Coward | more than 2 years ago | (#39407601)

If only accuracy were also included in that list of accomplishments. A helpful table of translations would help this problem. For instance, "never" means "probably not in testing" and "always" means "until somebody actually uses it."

Re:what's in a name? (3, Informative)

tibit (1762298) | more than 2 years ago | (#39408791)

I concur. Just ask the wine developers about how complete and accurate MS documentation is. They are reverse engineering a whole lot just because the documentation sucks in a way.

Re:what's in a name? (2)

Amouth (879122) | more than 2 years ago | (#39407643)

i'd agree with you for the old msdn.. but the latest generation annoys me.. while all the same information is there, they lack the old tree based view so you can find other related items with ease.. right now you can find documentation for what you want but it is no longer useful for finding something you want to use but don't know if it exists/what it is called exactly.

Re:what's in a name? (2)

cbhacking (979169) | more than 2 years ago | (#39409081)

It's still there. Switch to Classic reading mode - it's in the upper left, and may be obscured behind a gear-shaped icon, but it's there. The new modes are simpler and render better on mobile browsers, but the classis MSDN is still available for those who find it familiar and useful.

Re:what's in a name? (1)

cbhacking (979169) | more than 2 years ago | (#39409103)

Gah... upper right. My bad, sorry. The gear icon is labeled "Preferences" on mouseover. Mind you, this advice only works for the real MSDN documentation / reference stuff, not the new "Dev Center" BS.

Re:what's in a name? (1)

Amouth (879122) | more than 2 years ago | (#39412183)

thank you - my god i don't know how i missed that.. I've been dealing with the new version for so long.. it just isn't something i go into a lot, but when i go into i really need it.. and to be able to walk the documentation like the classic style lets you, that is real value to me..

again, thanks,., i do not know how i missed that.

Re:what's in a name? (1)

stephanruby (542433) | more than 2 years ago | (#39408371)

Microsoft's documentation is generally well organized, comprehensive, and the writing style is simple and concise; basically everything you'd want technical writing to be.

Microsoft's documentation is pretty good, yes, but publishing a book on it as the ideal example to follow (without any caveats) is a dis-service to the industry. It isn't until fairly recently that you couldn't find anything on MSDN without doing a Google search first.

And yes, it is nice that they mix knowledge base articles with forum posts in their search results now, but nothing beats the way I've seen Macromedia do it (now owned by Adobe) and that's to allow people to post comments directly at the bottom of each relevant document (and have them publicly visible!). This way, if something wasn't clearly documented, or if the documentation had a small mistake, it wasn't hidden from view, and as a developer, you didn't have to waste an hour's worth of work trying to find out on your own.

Re:what's in a name? (0)

Anonymous Coward | more than 2 years ago | (#39409595)

This is exactly how MSDN works on my end. At the bottom, there are relevant comments about the article I am writing. I don't know if it's from a forum or not, but they show up and are useful.

Re:what's in a name? (3, Interesting)

MtHuurne (602934) | more than 2 years ago | (#39408489)

There is a lot of bad documentation out there, so Microsoft's is probably above average, but I wouldn't call it good. At least the .Net documentation is a huge collection of example code fragments but contains very little text that actually explains what the methods do. Especially important details like how the method reacts when the input is invalid, the state is invalid, the operation fails etc are often missing. Or some hint about the underlying implementation, so you can get a feeling which methods have to do a lot of work and which will return quickly. You can't learn those things from a code example, they have to be documented explicitly.

Re:what's in a name? (3, Insightful)

Anonymous Coward | more than 2 years ago | (#39408931)

Microsoft's technical documentation is actually pretty amazing compared to other vendors

Microsoft's documentation is quite often piss poor. At times, as older versions of Windows have been deprecated, notes specific to those platforms have disappeared from MSDN as if nobody needs to write compatible software any longer. You search MSDN for a commonly named API or class, and you end up being shunted to a Windows CE or .Net article first, as if they were the most common platforms (maybe MS would like them to be). Trying to find information about security models, virtualization, and other features upcoming on a just-released OS tends to drive you to scour dozens of semi-related articles and blog posts from Microsoft engineers. This is a company that's been involved in lawsuits for undocumented APIs.

To call their documentation "amazing" is pretty outrageous. It may be "better than average", but considering their APIs are often fundamental to the development of Windows applications it's far from perfect.

Re:what's in a name? (1)

Savantissimo (893682) | more than 2 years ago | (#39410605)

And that's the good stuff they keep behind the counter at MSDN. The actual locally-stored help files are generally worth fuck-all. I can't remember the last time the MS help file told me something that wasn't obvious by inspection - everything they write is clear, simple and utterly useless.

Not that linux is effectively much better - imagine you had a thinko and accidentally typed your encrypted volume password at the command prompt - now try to find how to delete (let alone secure delete) a specific entry in your bash command history in the bash man page and you'll appreciate a little better searching and organization. Config file settings for most things are also woefully documented. Actually, linux documentation pretty much sucks. Even the best books really don't help with the fundamental cruftiness of the whole thing. You can maybe do anything, given enough time and experimentation, but even the people doing the documentation aren't willing to undergo the pain of actually figuring out how to use most of the software's capabilities.

Re:what's in a name? (1)

fuzzywig (208937) | more than 2 years ago | (#39412167)

Personally I've always found man pages to be either far too brief, or far too long, and always resorted to a quick web search instead, but then I'm more of a windows admin day to day.

Re:what's in a name? (2, Funny)

Lunaritian (2018246) | more than 2 years ago | (#39407549)

I don't care much about documentation, but if Microsoft released a manual for coding, then I would start worrying.

Re:what's in a name? (2, Insightful)

Richard_at_work (517087) | more than 2 years ago | (#39407581)

Microsoft Press have all sorts of technical books out. Most are of a very high standard.

Re:what's in a name? (1)

drodal (1285636) | more than 2 years ago | (#39407597)

Perhaps: "The Pompeii Manual of City Placement"

or

"The 1882 Home Buyers Guide: Krakatoa edition". (it blew up in 1883)

Re:what's in a name? (0, Insightful)

Anonymous Coward | more than 2 years ago | (#39407603)

Is there something wrong with Pompeii's architecture? A volcano is hardly a reason to dismiss any architecture to be found there. And actually, it'd be the Zeppelin company, and they did pretty well, since one of the names for airships is based on their names.

Re:what's in a name? (0)

Anonymous Coward | more than 2 years ago | (#39409503)

Yeah. Way to clear things up for us, genius.

Re:what's in a name? (0)

Anonymous Coward | more than 2 years ago | (#39407657)

ROFL! So true! You get my vote, which if I wasn't posting as Anonymous Coward you'd get... :rolleyes:

Re:what's in a name? (1)

inode_buddha (576844) | more than 2 years ago | (#39409773)

It makes me think of a three-way with Janet Reno and Margaret Thatcher.

Re:what's in a name? (2)

tehcyder (746570) | more than 2 years ago | (#39412179)

Amusing, but the fact that Pompeii got wiped out by a volcano wasn't the fault of the architects there, and certainly not of the people who wrote the architectural style guide.

Re:what's in a name? (0)

Anonymous Coward | more than 2 years ago | (#39412229)

"The Pompeii Manual of Architecture"

I understand your point and fully acknowledge the humor. It's the same thing I thought about "MS Manual of Style" (first thing I thought of was "Is it typeset in Comic Sans?"), but this analogy with Pompeii isn't really appropriate. Pompeii architecture is quite beautiful and functional. It just wasn't engineered to handle a 1000-degree-C pyroclastic flow [wikipedia.org] rolling over it.

How about "The Pompeii Manual of Geological Hazard Assessment"?

I do not see any mention of TeX (0, Offtopic)

betterunixthanunix (980855) | more than 2 years ago | (#39407507)

Clearly they have no idea what they are talking about if they do not make any mention of TeX. No discussion of bounding boxes or kerning? What sort of technical writers are not worried about overfull hboxes?

Re:I do not see any mention of TeX (0)

Anonymous Coward | more than 2 years ago | (#39407655)

What sort of technical writers don't know the different meanings of style? Oh yes, those wanting cheap digs at Microsoft.

Re:I do not see any mention of TeX (4, Informative)

expatriot (903070) | more than 2 years ago | (#39407665)

The CMOS and this are English style and usage guides for writers, not primarily a printing and layout guides. The CMOS is the industry standard, but it is too specific and has too many entries to be a quick reference. Most big companies have their own supplemental guide for "house style".

Re:I do not see any mention of TeX (2)

PCM2 (4486) | more than 2 years ago | (#39407769)

The CMOS is also not necessarily the best resource for technical writing. I haven't used it as a bible since the 14th edition, but in those days the CMOS simply had no concept of bullet points in text, for example. Eschewing bullet points is good advice for lots of types of writing, but for an instructional text on a highly technical topic they can be quite handy. CMOS also tends to be behind the curve on matters of styling technical jargon for technical audiences (preferring "e-mail" to "email," for example). The CMOS is still a good general reference for professional English style, but a book like Microsoft's fills in the gaps for a specific subject area. Most technical publishers maintain a similar document internally, though it probably won't be as exhaustive as Microsoft's.

Re:I do not see any mention of TeX (2)

jbengt (874751) | more than 2 years ago | (#39408027)

The CMOS is also not necessarily the best resource for technical writing.

Agreed. The Chicago Manual is the defacto standard for academic writing, but not necessarily standard for other types of writing.

Re:I do not see any mention of TeX (1)

Intropy (2009018) | more than 2 years ago | (#39408555)

I think MLA and APA styles are probably more common than Chicago. I'd bet not using a style guide is most prevalent.

Re:I do not see any mention of TeX (2)

X0563511 (793323) | more than 2 years ago | (#39407831)

The kind who do WYSIWY(t)YG in MS Word?

Re:I do not see any mention of TeX (0)

Anonymous Coward | more than 2 years ago | (#39408265)

TeX has nothing to do with style. You can choose between many different styles in TeX, AMS is probably the most famous one. In fact, you can choose any document style in TeX, and still use a different reference model (e.g. use IEEE style and have your references and bibliography in CMS format).

Re:I do not see any mention of TeX (2)

hackertourist (2202674) | more than 2 years ago | (#39411525)

Technical writers know that page layout and writing are two different disciplines. They know that writers needn't worry about the fine details of page layout because that's been taken care of by the template designer.

Not that this stops people asking the tech writer to change the layout ("but almost half the page is empty! If you decreased paragraph spacing by 1pt, you could fit that large graphic on this page!").
No, when writing a 400-page manual you can't lay out every page manually. Well, you could, but we're trying to spare you the sticker shock.

Embrace, Extend, Extinguish. . . (3, Funny)

dtmos (447842) | more than 2 years ago | (#39407517)

. . . now expanded to include the English language.

Re:Embrace, Extend, Extinguish. . . (1)

517714 (762276) | more than 2 years ago | (#39407941)

English has too many words, please use Newspeak.

CMS? (0)

Anonymous Coward | more than 2 years ago | (#39407537)

Great, another meaning for Content Management System.

Embracing open source?! (5, Interesting)

Anonymous Coward | more than 2 years ago | (#39407545)

"Microsoft has been criticized for their somewhat lukewarm embrace of open source. With the Microsoft Manual of Style, Microsoft is nearly freely sharing a huge amount of their intellectual capital. At $29 for the paperback and $10 for the Kindle edition, the manual has a windfall of valuable information at a bargain-basement of a price. "

Is this Microsoft astroturfing or is the author really that clueless about what free means?

1. I can't modify and redistribute. So it's not free-as-in-rights

2. It's $29, so it's not free as in beer

In what way is this guide supposed to be upholding OSS values?

Re:Embracing open source?! (1)

drodal (1285636) | more than 2 years ago | (#39407637)

It's free in the same way that a roach motel is a motel for roaches.........

Re:Embracing open source?! (2)

neonv (803374) | more than 2 years ago | (#39408459)

It's "nearly free" meaning they're not making money off of it. The price of buying it pays for the writing and publishing costs.

Re:Embracing open source?! (1)

Tanuki64 (989726) | more than 2 years ago | (#39411307)

If they do not make money off it, the most likely try to soil something.

Re:Embracing open source?! (2)

Just Some Guy (3352) | more than 2 years ago | (#39408511)

Microsoft is sharing an internal document that probably cost them a huge number of man-hours to produce, and they're selling it for a very reasonable price. In no way am I a Microsoft fan, but I think it's cool of them to make some pretty hard-won wisdom available outside their organization.

Re:Embracing open source?! (0)

Anonymous Coward | more than 2 years ago | (#39410889)

It is indeed cool, but I too am left wondering what the connection to open source was supposed to be...

Re:Embracing open source?! (0)

Anonymous Coward | more than 2 years ago | (#39409471)

Journalists use the AP styleguide. Those aren't free either, but the newspaper/ magazine/ publisher - in other words, your EMPLOYER typically buys them for you.

Re:Embracing open source?! (0)

Anonymous Coward | more than 2 years ago | (#39409719)

"Microsoft has been criticized for their somewhat lukewarm embrace of open source. With the Microsoft Manual of Style, Microsoft is nearly freely sharing a huge amount of their intellectual capital. At $29 for the paperback and $10 for the Kindle edition, the manual has a windfall of valuable information at a bargain-basement of a price. "

Is this Microsoft astroturfing or is the author really that clueless about what free means?

1. I can't modify and redistribute. So it's not free-as-in-rights

2. It's $29, so it's not free as in beer

In what way is this guide supposed to be upholding OSS values?

NEARLY Free. Like Nelson Mandela for 27 years. Like NEARLY legal your honour I swear! Like nearly broke the world record. Like Maxwell Smart "missed it by that much". Like "a little bit pregnant".

In this context he means cheap $$$ wise. It's just a weasel word way of saying it.

Re:Embracing open source?! (1)

drodal (1285636) | more than 2 years ago | (#39415831)

I have to agree with the poster here. This is a fine book, and microsoft is sharing this information (for a price). This is very good old school practice.

But to compare it with open source is really really bad and reaching. The whole, "Can't modify and redistribute" thing is the 900 pound gorilla here.

One of the most important things about open source is the right to modify and redistribute.

The whole thing reeks of non FOSS. A good example of old school vs new school. Look at the java documentation online anywhere

It's pretty nice. Now look a the PHP documentation. See how at the bottom of EVERY page php as user contributed examples and comments.

I usually find these WAAAAAAY  more useful that what's above them. Java never has these.

to me it's the difference between night and day.

one place, your peers help you (the bizarre), the other makes a sale(the church). (probably helps too)

Link is to 3rd edition (0)

Anonymous Coward | more than 2 years ago | (#39407553)

The review is for the recently published 4th edition: http://www.amazon.com/Microsoft-Manual-Style-Corporation/dp/0735648719

Oxymoron (2, Funny)

FridayBob (619244) | more than 2 years ago | (#39407577)

'Nuf said.

It has company (1, Funny)

Tablizer (95088) | more than 2 years ago | (#39407615)

It's in my bookshelf, right next to Apple's Guide to Open Systems.

Re:It has company (0)

Anonymous Coward | more than 2 years ago | (#39409667)

No one other than one chucklefuck is rating you funny at the time of this writing because you're a complete idiot if you think this has anything to do with programming. Their documentation is excellent.

I'm sure more idiots will follow the bandwagon though.

Re:It has company (1)

Tablizer (95088) | more than 2 years ago | (#39410595)

Relax, Dude, we're just having a little geekfun

One question (1)

Lunaritian (2018246) | more than 2 years ago | (#39407675)

Does the book also tell how to get the users to RTFM?

The only thing rarer than a well-written manual is a person who actually reads it.

Re:One question (1)

PCM2 (4486) | more than 2 years ago | (#39407811)

Well, that's kind of the whole point. Making manual text more consistent and easier to scan and parse makes the manual more readable, so it will be less daunting to newbies.

The MMoS also includes advice on how to style text in dialog boxes and online help to make them more legible and less frustrating to users.

DEC had great manuals (4, Informative)

Nutria (679911) | more than 2 years ago | (#39407689)

Their Big {Orange,Grey,Blue} Walls were paragons of thoroughness and clarity.

Best news was that since it's was all done on computer, their on-line help system had exactly the same text as the dead tree manuals.

Re:DEC had great manuals (1)

tibit (1762298) | more than 2 years ago | (#39408819)

Borland Pascal documentation was done the same way!

Oh Noes!!! (5, Funny)

dskoll (99328) | more than 2 years ago | (#39407749)

pronounI verbHope pronounThey verbDon't verbEncourage adjHungarian nounNotation!

Re:Oh Noes!!! (1)

subreality (157447) | more than 2 years ago | (#39410641)

There are two kinds of Hungarian Notation:

Good: centigradeDegrees
FAIL: integerDegrees

Re:Oh Noes!!! (2)

DavidD_CA (750156) | more than 2 years ago | (#39410839)

Either way, if you're storing your measurement of temperature as an integer... you've got bigger problems than what you name the variable.

(Yes, I know we don't always need decimal precision for temperature. This was meant as a snarky comment and nothing more.)

Microsoft's Style ... (5, Interesting)

sk999 (846068) | more than 2 years ago | (#39407797)

I always find Microsoft's documentation to be characterized consistently by two properties:

1. Tons of GUI screen shots. 20 pages of dead trees or dead electrons to convey a single paragraph's worth of actual information.

2. There is no universe outside of Microsoft. They can't acknowledge it even when they try. Example - Microsoft Exchange is notorious for violating the IMAP standard for RFC-822 message size. Microsoft's documentation actually acknowledges that Exchange does something different, but calls it a "clarification" of the standard. Right.

Re:Microsoft's Style ... (1)

dskoll (99328) | more than 2 years ago | (#39407967)

Tons of GUI screen shots.

Isn't that the nature of the beast? Documenting systems that rely heavily on GUIs is a real PITA. For example:

Unix doc: "To prevent others from accessing your file, execute: chmod go-rwx file "

WIndows doc: "Right click here, choose "Permissions" or whatever, go to the "Access" tab, enable the "frobnitz" checkbox..."

Aieeee!

Re:Microsoft's Style ... (1)

Grishnakh (216268) | more than 2 years ago | (#39408541)

It sounds to me that sk999 is complaining that they use too many screen shots for the amount of information. For instance, unless you're speaking to a really clueless/newbie crowd, you don't need to have a screenshot for every single step you take, just the ones where there's likely to be some confusion. Of course, though, it depends on the intended audience. If it's a book for Windows newbies, then yes, you probably do need a screen shot showing the start menu being clicked on. If it's a book for experienced programmers, you can leave that stuff out.

Re:Microsoft's Style ... (1)

dskoll (99328) | more than 2 years ago | (#39408959)

Ah, could be. This might be a "Microsoft Universe" problem.

We sell software that has a Web interface, and we've had customers take a .BMP image of Internet Explorer, embed it in a Word document and attach the Word document to an email when they could have cut-and-pasted a 50-character error message from the Web interface. :(

Re:Microsoft's Style ... (1)

tehcyder (746570) | more than 2 years ago | (#39412253)

1. Tons of GUI screen shots. 20 pages of dead trees or dead electrons to convey a single paragraph's worth of actual information.

Just think of the electrons!

Re:Microsoft's Style ... (0)

Anonymous Coward | more than 2 years ago | (#39414327)

Well, RFC 882 has been superseded twice, and is no longer a valid standard. You should be designing against RFC 2882...

From Latin ("de" + ablative of "factum") (0)

Bromskloss (750445) | more than 2 years ago | (#39407817)

The Chicago Manual of Style (CMS), now in its 16th edition, is the de facto style guide for American writers.

You see, it's not actually a style guide, only de facto so.

Re:From Latin ("de" + ablative of "factum") (1)

PCM2 (4486) | more than 2 years ago | (#39407873)

This is also only true for many American writers. Many others prefer the Associated Press Stylebook. The two differ on various points.

Re:From Latin ("de" + ablative of "factum") (1)

Troy Roberts (4682) | more than 2 years ago | (#39408861)

I see you think you know latin and thus assume you under stand "de facto". Just in case, you are confused on this point, let's see what Merriam-Webster says:


1. de facto
adv \di-fak-()t, d-, d-\
Definition of DE FACTO
1: in reality : actually

2. de facto
adj
Definition of DE FACTO
1: actual; especially : being such in effect though not formally recognized
2: exercising power as if legally constituted
3: resulting from economic or social factors rather than from laws or actions of the state

His usage looks good to me.

Re:From Latin ("de" + ablative of "factum") (1)

Bromskloss (750445) | more than 2 years ago | (#39409215)

I'm afraid I don't follow you. The M-W definition is consistent with what I had in mind. Maybe I should explain what I meant, in case it was misunder stood.

Pro primo, let us establish that we agree on the following usage: "Our company has set no standard regarding what file format to write text documents in, but everyone has gravitated toward LaTeX, so it is the de facto standard." Pro secundo, I interpret my sentence about the CMS analogously, like so: "The CMS was never intended to be a style guide, but everyone is using it as such anyway." Of course, it was intended to be a style guide all along, hence my picking on the formulation in the book review. If the CMS is the dominating style guide, you could say that it is the "de facto standard when it comes to style guides", though not an actual, official standard.

I could also be all wrong; that wouldn't be unprecedented.

Re:From Latin ("de" + ablative of "factum") (1)

tehcyder (746570) | more than 2 years ago | (#39412311)

Cool, a Latin Grammar Nazi flamewar/bitchfest.

That's not something you see every day.

Re:From Latin ("de" + ablative of "factum") (1)

Bromskloss (750445) | more than 2 years ago | (#39412393)

Yay! I have no idea what "bitchfest" mean, though. That's totally like Greek to me. ;-)

Re:From Latin ("de" + ablative of "factum") (1)

Troy Roberts (4682) | more than 2 years ago | (#39412805)

I suppose I was confused by your sarcasm and the fact that there is not agreed upon style guide for American writers.

Ark of the Covenant (0)

CanHasDIY (1672858) | more than 2 years ago | (#39407893)

Seriously, when I read the phrase "Microsoft Manual of Style," All I see in my head is that scene from Raiders where that one Nazis face is melting...

Problems in computer science (1)

Bromskloss (750445) | more than 2 years ago | (#39407959)

- We have this "travelling salesman" problem.

- I see. Oh, I know! Let's call it "sales representative" instead.

At the Amazon link in the post (1)

aoeu (532208) | more than 2 years ago | (#39408061)

The Third edition is available new for only $240.96. The fourth edition, reviewed here is available for $19.99. QC fail.

poor tables (1)

bauerbob (1049344) | more than 2 years ago | (#39408789)

Is it only the electronic edition of amazon or are the tables in this book really that ugly? That's pretty disappointing when you've got a "style" guide in your hands.

I'm a huge fan of the The Chicago Manual (2)

brokeninside (34168) | more than 2 years ago | (#39409341)

... nevertheless, the claim that CMS is ``the de facto style guide for American writers'' is overblown at best. In academia, I would be surprised if even a plurality of journals preferred CMS. The graduate school I'm attending prefers it but most journal articles I read certainly use other style guides.

Moreover, as someone who does technical support for a living and reads MSDN and TechNet quite a bit, I can tell you first hand that the claim that ``Anyone who has read Microsoft documentation knows it has a consistent look, feel and consistency'' is utter bunk.

A question that was not addressed by this review, I think, is quite telling. What does this style guide have over and above such style guides as the venerable CMS (my preference) or other style guides (APA, MLA, the EU's Interinstitutional Style Guide, et cetera)?

This is a review? (0)

Anonymous Coward | more than 2 years ago | (#39409565)

It's a shallow recitation of the table of contents with little details thrown in for a splash of color. It doesn't say why the book is good, nor where it is deficient. In fact, it reads too much like the worst of technical writing.

Simply reciting facts, or regurgitating screenshots without any real context behind them, is cheap writing that doesn't do much good for anybody. This review seems to be along the same lines.

This sentence from near the end of the review sums it up perfectly: "Many authors simply write in an ad-hoc manner." That's a perfect description of his own review. A review should tell a story. It should have connections between paragraphs. It should be written to engage the reader. It needs to have some sense of unity.

Sigh. Enough ranting for today.

Eh? (0)

Anonymous Coward | more than 2 years ago | (#39409973)

Seems a bit of an oxymoron to mention M$ and style in the same breath...

huh (1)

Johann Lau (1040920) | more than 2 years ago | (#39411099)

IE – never abbreviate Internet Explorer; always use the full name

Say what you will about Microsoft, but any technical writer who is serious about being a better writer can learn a lot from the writers at Microsoft.

That's hilarious!

Microsoft has been criticized for their somewhat lukewarm embrace of open source. With the Microsoft Manual of Style, Microsoft is nearly freely sharing a huge amount of their intellectual capital.

That's daft.

TFR used what style guide? (1)

UnoriginalBoringNick (1562311) | more than 2 years ago | (#39411321)

Haven't read TFB and stopped reading TFR at this line:

"The book is made up of two parts; with part 1 comprised of 11 chapters on general topics. "

I wonder what is Microsoft's position on the use of the word 'comprise'

https://encrypted.google.com/search?q=how+to+use+the+word+%22comprise%22 [google.com]

Another boring-ass 10/10 review (0)

Anonymous Coward | more than 2 years ago | (#39411447)

Dealing with 'technical writing style' from a company well-known for exactly their excellent style and technical writing. Every one of their products comes with a readable, useful user manual and their online resources are even better! Bonus!

Perhaps the reviewer should have read it (1)

dzfoo (772245) | more than 2 years ago | (#39413313)

I have to stop reading after the first few paragraphs.

A style guide or style manual is a set of standards for the writing and design of documents...

Anyone who has read Microsoft documentation knows it has a consistent look, feel and consistency...

Style guides by their very nature of highly subjective and no one is forced to take accept the Microsoft style as dogma.

Is there a Microsoft Manual of Grammar available?

Load More Comments
Slashdot Login

Need an Account?

Forgot your password?

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>