Take the 2-minute tour ×
Writers Stack Exchange is a question and answer site for authors, editors, reviewers, professional writers, and aspiring writers. It's 100% free, no registration required.

I currently work for an engineering company as an electrical engineer. A good chunk of my time is spent writing testing reports or instruction documents. Currently my company doesn't have any sort of guidelines specifying how to format documents, and everyone seems to do it a different way.

I considered buying the Chicago Style Manual because it is suggested by the IEEE (a prominent electronics organization). This is a massive book at nearly 1,000 pages. Does anybody here have any input whether reading through a manual like this is a worthy expenditure of time for someone in a field like mine?

share|improve this question
1  
The Chicago Manual of Style Q&A is a great way to ease yourself into CMOS; I highly recommend subscribing to the mailing list. –  Neil Fein Apr 2 '12 at 16:25
1  
@NeilFein - Are you suggesting that this process is so daunting that it will turn the OP into a semiconductor? LOL (complementary metal oxide semiconductor) –  Joe Apr 5 '12 at 23:29
    
@Joe - Only if the writer is bathed in liquid grammar. –  Neil Fein Sep 20 '12 at 20:44

6 Answers 6

up vote 3 down vote accepted

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer

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 creating 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.

share|improve this answer

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).

share|improve this answer

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?

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.