Re: Advice on starting out; dealing with employers

Subject: Re: Advice on starting out; dealing with employers
From: Gregory P Sweet <gps03 -at- health -dot- state -dot- ny -dot- us>
To: Joan Wamiti <jwamiti -at- breakeveninc -dot- com>
Date: Mon, 18 Apr 2011 10:10:36 -0400

> 2. What should I keep in mind when dealing with my employer? My bosses
> have technical backgrounds and only have the haziest idea of what their
> requirements are - they want a wiki, client-specific help guides, and a
> blog. They have no idea of what a style guide is or why anyone would
> one. I feel like I come off sounding fussy and pedantic about getting
> documentation right, but I want to do a really good job with it, even if
> just a beginner. I've clarified who my primary audience is (the
> and the blog isn't a priority right now.

Use their technical background to your advantage.

I usually draw a comparison to the programming language they know and use.
How it has specific syntax and conventions so that it is easily understood
by the compiler or rendering engine, and if there are errors in the syntax
the output is not rendered or is misunderstood and rendered incorrectly.

A style guide is the syntax and conventions of your programming language
that allow the rendering engine (the reader) to easily understand the
output (the document). And just as maximum efficiency is achieved in a
software system when all the modules and applications use a consistent
syntax, shared objects, etc. the users will have the best, most efficient
experience with the documentation when it is consistent in style and

Burst the "But it's just English, and everyone can write English!" argument
by reminding them that their software is written in English, a special form
of English to be sure, but still English. And just as the software requires
its own special form of English, documents need a special form of English,

If they still don't buy it, remember who signs the paycheck and do what
they want.



IMPORTANT NOTICE: This e-mail and any attachments may contain confidential or sensitive information which is, or may be, legally privileged or otherwise protected by law from further disclosure. It is intended only for the addressee. If you received this in error or from someone who was not authorized to send it to you, please do not distribute, copy or use it or any attachments. Please notify the sender immediately by reply e-mail and delete this from your system. Thank you for your cooperation.


Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Please move off-topic discussions to the Chat list, at:

Advice on starting out; dealing with employers: From: Joan Wamiti

Previous by Author: Re: It is Friday...
Next by Author: Re: Is there a free/cheap equivalent to Dreamweaver?
Previous by Thread: RE: Advice on starting out; dealing with employers
Next by Thread: Re: Advice on starting out; dealing with employers

What this post helpful? Share it with friends and colleagues:

Sponsored Ads