Microsoft Manual of Style for Technical Publications

This forum is for the discussion of the business and craft of writing help. For example writing style, choices of HTML Help or WinHelp or browser-based and so on...

Moderators: Alexander Halser, Tim Green

Post Reply
User avatar
Alexander Halser
EC-Software Support
Posts: 4098
Joined: Mon Jun 24, 2002 7:24 pm
Location: Salzburg, Austria
Contact:

Microsoft Manual of Style for Technical Publications

Unread post by Alexander Halser »

Microsoft Manual of Style for Technical Publications

Complete styles and guidelines for publishing a variety of technical publications.

Download: http://www.microsoft.com/downloads/rele ... seID=44354
Version: 3.0
Release date: 21 Oct 2002
File format: Microsoft HTML Help

From the manual:
"The Microsoft Manual of Style for Technical Publications (MSTP) is intended to give clear, up-to-date, and easy-to-use advice about usage and spelling of both general and computer-related terms, sentence style, technical writing issues, and design and interface elements.

As before, this guide is to help Microsoft writers and editors maintain consistency within and across products. It is not a set of rules. It does provide guidelines that have been discussed and reviewed by experienced writers and editors across the company. These guidelines represent their expertise and opinions of what best serves Microsoft documentation teams and their customers.
"
Alexander Halser
Senior Software Architect, EC Software GmbH
WhiteEC
Posts: 1
Joined: Mon Jan 23, 2006 6:01 pm

Microsoft Manual of Style for Technical Publications

Unread post by WhiteEC »

Link no longer works.

/s/ Gene White
whiteec@sbcglobal.net
User avatar
Van Swofford
Posts: 38
Joined: Thu Feb 05, 2004 5:42 pm
Location: Brentwood, TN

Re: Microsoft Manual of Style for Technical Publications

Unread post by Van Swofford »

WhiteEC wrote:Link no longer works.
It appears they have released it in book form at:
http://www.microsoft.com/MSPress/books/6074.asp
"Half of what I say is meaningless..." -- John Lennon
"Your job is to figure out which half" -- Van Swofford
jakeoh
Posts: 20
Joined: Thu Dec 18, 2003 7:55 pm

Unread post by jakeoh »

Marcus McCrory
Posts: 8
Joined: Thu Jul 18, 2002 6:35 pm
Location: Minneapolis, USA

Unread post by Marcus McCrory »

I have the third edition of the Microsoft publication and it has been very helpful. Are there any other texts worthwhile reviewing?
Marcus McCrory
The Cirius Group, Inc.
User avatar
Jasmine Andrews
Posts: 15
Joined: Wed Apr 08, 2009 7:40 am
Location: Sydney, Australia

Unread post by Jasmine Andrews »

In my opinion, Read Me First by Sun is a better style guide than the Microsoft one, but both are good.

I can also recommend a few other books that I use alot (not style guides):

Single Sourcing: Building Modular Documentation Kurt Ament

Is the Help Helpful? How to create online help that meets your users' needs Jean Hollis Weber

Managing Your Documentation Projects Joann T Hackos

The help I am currently working on is more a knowledge base than a system support tool, so I am approaching it like an intranet. I bought Don't Make Me Think to understand web site usability and alot of the concepts transfer well.

I have also ordered Information Architecture for the World Wide Web by Rosenfeld and Morville from Amazon as it has got great reviews and I read a excerpt that was very interesting. I forgot what else I have ordered. I read alot and can't keep track sometimes!
Marcus McCrory
Posts: 8
Joined: Thu Jul 18, 2002 6:35 pm
Location: Minneapolis, USA

Unread post by Marcus McCrory »

Appreciate the recommendations - cheers.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

The other recommendations are great but I would always be careful depending on anything that comes from Microsoft on the subject of documentation, because viewing Microsoft as any kind of authority on documentation is something of an oxymoron. It would be a little like expecting to be able to depend on a book by Microsoft titled The Importance of Web Standards. 8)
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
John Waller
Posts: 827
Joined: Thu Apr 20, 2006 9:34 pm
Location: Adelaide, South Australia

Unread post by John Waller »

A little harsh, perhaps, Tim? MSDN is surely an excellent example of Microsoft's current high standards?
Regards

John Waller
v.6.2.2 Build 2636
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Hi John,
John Waller wrote:A little harsh, perhaps, Tim? MSDN is surely an excellent example of Microsoft's current high standards?
I still have mixed feelings, even there. There's a huge amount of information in MSDN but it's really not very accessible. My main objection to Microsoft's approach to documentation is that it's dictated more by economic considerations than usability -- for example the almost complete elimination of anything but text from Windows help, which is exclusively a time and money decision. That might be forgivable for companies that can't afford anything better, but not for a company in Microsoft's position and with their effectively unlimited resources.

What I'm really trying to say is that there is no need to be awed by Microsoft here or to take them as the number one model to be followed.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
User avatar
John Waller
Posts: 827
Joined: Thu Apr 20, 2006 9:34 pm
Location: Adelaide, South Australia

Unread post by John Waller »

Tim Green wrote:What I'm really trying to say is that there is no need to be awed by Microsoft here or to take them as the number one model to be followed.
Agreed but I'd still include them on a list of recommended reading :)
Regards

John Waller
v.6.2.2 Build 2636
User avatar
Greg Smith
Posts: 209
Joined: Thu Feb 01, 2007 4:52 pm
Location: Cambridge, England

Unread post by Greg Smith »

The various Microsoft and Apple style guides I have read over many years do have good points... it is a shame that MS don't actually follow the spirit of them. As an active user of MS technical documentation, which often is fairly obviously taken from header files of source code, I am generally frustrated. They will always tell you what each argument and function is, but never tell you what it is for. I have several times hit problems when dealing with implementations of APIs where a third party company has managed to misinterpret MS documentation. There is an old story about MS doc that I'm sure you must have come across:

"A light aircraft is lost in the fog and flying aimlessly around Seattle. Eventually the pilot and his passenger find a tall building and can just make out a man at an open window. The passenger shouts out, 'Where are we?' and the man shouts back, 'In a 'plane', whereupon the pilot flies immediately to the airport and lands safely. The passenger is incredulous and demands an explanation. 'Well', says the pilot, 'what we were told was completely accurate and also totally useless, so this must be the Microsoft Documentation Centre, which is close to the airport."

Well-written standards are worthwhile, but good documentation really depends on good documentation writers.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

Hi Greg,

To do Microsoft justice, Adobe is even worse on this. Their documentation is full of descriptions of functions that don't tell you where the function is in the program. After using search to find the description of exactly the tool you need to solve your problem you then spend the next hour hunting through the $!%&§ program trying to find the function described. :roll:
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Post Reply