Is it overkill to follow style-guides for technical writing?

I don't think following a style guide is overkill. It's really helpful to have an authoritative answer to things like whether to use e-mail or email and not have to look them up a dozen times or argue over them with other people. However, CMOS is probably too detailed for your needs, and I certainly wouldn't read it cover to cover. Even as someone whose whole job is writing, I wouldn't sit and read a style guide from front to back. For an electrical engineer, I don't think that's a good use of your time.

Currently on my bookshelf, I have The AP Stylebook and The Microsoft Manual of Style. I like both, although AP doesn't use serial commas and I personally like serial commas. Microsoft is really helpful for software instructions because it defines how to format button, window, screen, and menu names.

It might actually be more useful to write up your own style guide and create a template for the documents you write most. The style guide can be a simple list of style decisions; it doesn't need to include everything under the sun. When I write user manuals, I list all the parts of the interface and how to style those terms. (For example, if the application has a small 3D map for navigation, I note whether it's called the Mini Map, the Mini-Map, the 3D Map, the Navigation Map, or whatever.) I also include any terms that come up that have more than one standard spelling or hyphenation. Every time I have a question about a term when I'm writing or editing, once I resolve it, I add it to the list.

You can use that style guide just for yourself or, depending on how much pull you have and how much your organization cares about writing consistency, share it with the rest of your team.

IEEE Standards are a good resource for developing templates, because their standard for a given document usually includes a sample outline and a description of the content for each section. It's generally not too hard to set up a Word document with the specific formatting you want, the sections all laid out, and comments indicating what should actually go in those sections.

posted over 12 years ago

CC BY-SA 3.0

Kelly Tessena Keck‭

15 reputation 0 3 3 0

I think you are confusing a style guide with a manual of style. The Chicago Manual of Style will help, but is more of a reference book of best practices, rather than a set of policies and procedures to guide document development processes for your particular business use.

It seems a style guide is what you are hoping to create and implement company-wide, something that standardizes things like sections in a report or user guide, typefaces used, logo and trademark usage, software to be used to create documentation, and template design standards. Do a web search for "technical style guide" and you will find examples.

Creating the style guide will not be your biggest task, however. Getting management to implement it as a requirement will be the greatest challenge, and if you don't have that, you will waste your work and annoy yourself and your coworkers. The key to getting management buy-in is to get them to understand that consistent documentation is part of consistent branding and messaging - your documentation is a part of the marketing effort.

Once you have management behind your effort, bring in your colleagues and work as a team to create a style guide tailored to your company culture and work flows. Include key members of engineering, customer service, and marketing teams in this effort as well, so that you get engineering on the same page with scheduling documentation lead times, learn about what in the documentation is confusing or frustrating customers from the people who have to deal with them regularly, and ensure that the terms you are using in the documentation are the same ones the marketing department uses, also that you are targeting the right audience by understanding the actual customer base and their real world use of the products.

Some style guides also cover document distribution processes and retention policies. These can be also be dealt with in separate procedures, as best fit your business use.

posted about 12 years ago

CC BY-SA 3.0

Keter‭

5 reputation 0 1 1 0

No, it is not overkill to follow a stylebook. As others have said, you consult it as questions arise and learn as you go; you normally don't read it cover to cover. We all put sticky notes on the oft-consulted sections. Since you went to the trouble of asking your question, you are obviously bothered by the lack of consistency within your company.

Also, since you write a lot for your job, chances are you ARE already following a style. I would suggest you begin compiling a document including all of the things you are constantly looking up and create your own style guide. Who knows, maybe your company will one day adopt your guide! (One suggestion: as you compile your own guide make a note of which authoritative source you base each "rule" on so that you can refer back to it if necessary.)

My company follows The Associated Press Stylebook, except when they don't. We have a Word document with the exceptions, which is updated as decisions are made. (It is always noted in the file the date when a rule is changed.) Also, AP changes their style on occasion, and my company has to decide if they agree. As an example, last year AP changed e-mail to email. My company did not.

posted over 12 years ago

CC BY-SA 3.0

JLG‭

20 reputation 0 4 4 0

If the documentation is only ever going to be written by one person, and read by the same group of people, that documentation does not require a style (assuming it is internal documentation, not going to customers). As long as both sides understand it, it can work, although it may take newcomers to the reading a while to understand. If writing it in biblical Greek works for this situation, there are no problems with doing that.

However, almost all documentation, even internal, will be written by more than one person, and read by different people over time. It may be instructions for testing, but QA auditors may also need to see it. Instruction documents may be initially intended for a set groups, but they might then be stored for new people. Therefore, some form of standards are a good idea, although they may not need to be as rigorous as for external users.

The purpose is not to ensure that everything is always consistent and professional, it is to ensure that new people can understand and interpret documentation the correct way. So minor typos are not so important, but clarity and consistency are.

posted over 12 years ago

CC BY-SA 3.0

Schroedingers Cat‭

115 reputation 1 13 23 0

The AP is very similar to the Chicago Manual of Style, but much easier to use. Why go against the grain? You're going to reach the broadest possible audience with the AP, which I believe should be the ultimate goal here.

posted almost 9 years ago

CC BY-SA 3.0

Joe Schmoe‭

5 reputation 0 1 1 0

Not overkill at all. However, the Chicago Manual of Style is not really ideal for technical writing (and is intended as a look-it-up reference, not a cover-to-cover read). It is a good guide to general, formal writing for Americans. For a more international audience, the equivalent is The Oxford Guide to Style (a.k.a. New Hart's Rules, also published as half of Oxford Style Manual).

The principal problem with Chicago is that its editors are strongly opposed to the use of logical quotation (i.e., including within the quotation marks nothing that was not present in the original quotation) except for "textual criticism" and "computer code and commands". They otherwise recommend nothing but American journalism- and fiction-style quotation punctuation, in which periods (stops, dots) and commas are always placed inside the quotation mark even if they don't logically belong there. This is a terrible idea in any technical, or other precise, form of writing, though it remains favored by the AP Stylebook and other American journalistic style manuals.

If technical writing is your job, I'd advise owning the Chicago, Oxford, and AP manuals (as well as any other style guides you may need, e.g the legal Bluebook and Redbook, and Oxford equivalent, OSCOLA, which is a free PDF; and/or the CSE, AMA and APA science/medical style guides). Adapt your style as necessary. For business communication to Americans, use Chicago; for PR materials intended for Americans, use AP, for an international audience, rely on Oxford (also when quoting with high precision, e.g. typed commands or the labels on device controls). Turn to CSE, etc., as needed for scientific writing. You might also be called upon sometimes to comply with MLA Style Manual for some purposes. These books are all a good investment for any professional writer of non-fiction. So is updating them to new editions as they are released; sometimes the changes are significant. Effective use of language is a moving target.

posted about 9 years ago

CC BY-SA 3.0

S. McCandlish‭

5 reputation 0 1 1 0

Purchase it? Yes. I don't think you need to read it cover-to-cover unless you're a serious language geek who reads dictionaries for fun. ::cough::cough::

(Pulling out my 14th edition for reference...)

I would try to read as much of "The Parts of a Book" and "Manuscript Preparation" as you can before your eyes glaze over. Unless you're reading someone else's work, you can skim the proofreading section. "Design and Typography" would be good to read as well.

Everything else you can look up as you come across it: Do I use the serial comma? Does this sentence take "which" or "that"? How do I cite a website in a bibliography?

posted over 12 years ago

CC BY-SA 4.0

Lauren Ipsum‭

2098 reputation 13 1143 397 1

For documentation that will be published outside your organization, it is usually important to follow a style guide (pretty much any one) so that all the documentation reads with one "voice" even though it was written by a bunch of different people. As noted by Lauren Ipsum, you don't read the style guide cover-to-cover but, rather, consult it on individual points. (You'll need to become familiar with what points it covers, though.)

I said it is "usually" important; you should ask the question first before proceeding to adopt a guide. There is an existing practice of "every man for himself"; are things that way because it really doesn't matter to the people in charge, or only because the question has never come up? If it's not important to them, then you'll need to make a case that it matters in proportion to the cost of adopting a new practice. The purchase price of the book is noise; the cost will be in changing everyone's work habits. If customers (or other important people) see this documentation then that may well be an easy pitch; if it's only used by the members of your team, it might not matter (much as it pains me, as a writer, to say that).

posted over 12 years ago

CC BY-SA 4.0

Monica Cellio‭ staff

2514 reputation 51 268 361 110