Grammar

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
gail
Posts: 26
Joined: Thu Jul 05, 2007 2:33 pm
Location: England

Grammar

Unread post by gail »

Hello,

Just like to say we're getting on really well now using H & M to produce our docs, and thanks to everybody who helped out with the problems we had getting started with it.

Following on from the previous topic on Help Authoring, coming from an IT background myself, I am finding it a bit challenging just to know whether or not I am writing things in a consistent grammatically correct way!!! We have ordered a few books on this, but I was wondering if anybody could help with my capitalisation problems? For example some typical sentences we are using right now are:

1) Specifies information about the Work Group
2) The Date and Time should be declared...
3) Allows views of Transactions
4) The Technical Work Basket

The questions I have are:

1) There are many different work groups, so should work group be capitalised here, or just italicised because it is important?
2) Date and Time are variables within the programming languages. So I'm thinking they should be capitalised?
3) There are many transactions, so is it wrong to capitalise this?
4) Is it right to capitalise the Technical Work Basket, because I'm referring to a specific work basket here?

If anybody has a bit of time to answer these questions it would be much appreciated. I suppose the main thing is to take a consistent approach, but it is a bit challenging because I have read so many different ways to format help documentation!!
User avatar
Dean Whitlock
Posts: 577
Joined: Thu Sep 01, 2005 5:59 pm
Location: Thetford Center, Vermont USA
Contact:

Unread post by Dean Whitlock »

Hi Gail,

You are right that there are many approaches to formatting help, and whatever replies you get here should be read with that in mind, including mine! Here are my opinions:

1. Don't overdo it. Too many initial caps will make a sentence confusing. Same goes for using italics, bold, quotes, etc.

2. As you say, set up rules and be consistent.

3. Regarding Work Group and the other fielded data: If you are referring to a field that must be filled in, use caps (e.g., Fill in the Work Group name.) But don't cap it when referring to it in general (e.g., When labeling work groups, pick names that...).

4. I prefer to use init caps for fields names and button labels but also bold the button labels: e.g., Press Exit to...

5. I use italics for emphasis. In some outputs, bold-italic is actually easier to read, so use your judgement. I also use italics for report titles and manual titles. I don't use underlines because they can be confused with hyperlinks.

5. I use quotes around prompts and messages from the software and copy their text exactly, including caps (even if I disagree with the programmer's grammar).

Those are my basic rules, to be taken with a grain of salt.

Good luck,
Dean
User avatar
Jim Huskey
Posts: 54
Joined: Tue Jan 17, 2006 4:09 pm
Location: Universal City TX
Contact:

Unread post by Jim Huskey »

Gail,

Dean's ideas make a lot of sense. I think he covered all the basics. His suggestions make it easier to get to the point while still being very descriptive.

In my opinion, you have to tailor your style to both the readers and the demands of whoever's paying you. For instance, if you work for a defense contractor in the U.S., there is usually a style manual with guidance that you must not contradict with your style.

Sometimes you can, or should, make up the rules yourself. In my present job, I'm lucky - I'm the Lone Tech Writer. I use Dean's basic rules and make up a few of my own that I've learned over years of writing, and impose these as "The Style". I always use active and personal voice sentences, Subject-Verb-Object style, "You should" vice "Users should", and implied subjects when useful ("Select the No Defaults option to..."). I completely avoid passive stuff ("It is suggested that...") since it's useless and bloated.

I'm not a huge Microsoft fan, but they have a Manual of Style for Technical Publications that I also use when I run across things like "Click the button" vice "Click on the button" or "use the spin buttons" versus "click the arrows to". It helps to have backup if somebody wants to argue about it.

Whatever you choose to do, do it with an air of assertive knowledge.

Jim
gail
Posts: 26
Joined: Thu Jul 05, 2007 2:33 pm
Location: England

Unread post by gail »

Thanks guys for your suggestions. They were really helpful as we haven't really written this kind of thing before and have to make up our own style. We should hopefully be getting the Microsoft book, and also the Chicago Style Guide through soon. I will take your advice and try not to make it too cluttered with caps and style, and also be a bit more confident about the style we decide to use :)
User avatar
Dean Whitlock
Posts: 577
Joined: Thu Sep 01, 2005 5:59 pm
Location: Thetford Center, Vermont USA
Contact:

Unread post by Dean Whitlock »

Hi Gail,

A comment on the Chicago Manual of Style - it's a massive tome that appears to be intended for academic publishing - quite the opposite of the "keep it simple" school that Jim and I advocate. I also found its topic numbering system to be very hard to get used to. Your best bet for a guide, I think, would be "The Elements of Style," by Strunk & White. Or the "Washington Post Handbook of Style", although it's more geared toward journalistic grammar.

Remember that the goal of technical documentation is to clearly explain how to do something. If it's to use software, you want to describe its components and break its procedures into steps in as straightforward a manner as possible. Pretend the reader is sitting right next to you while you're showing them how to use the software. Figure out what questions they'd ask, and answer them as though you were speaking to them, while pointing to the headings, prompts, fields, and buttons.

Good luck!
Dean
Post Reply