an interesting example of "punctuation " and how it can make an incredible difference in the impact & tone of your writing:

Many times in our professional lives, from the first days of our first job, through the end of our career (notice the change from "job" to "career") we're asked to create a piece of documentation for either someone specific (our manager, our employees, or a group to whom we give a public presentation) or for some more general purpose.     We almost always do this with little thought as to the many aspects of documentation, because most of us believe if we can read, write & speak English (assuming we all do?) that we can document something.

However, in many cases, it's because we don't think much about the form or format of the documentation that we don't really do a very good job of it.

Consider documentation for these types of applications - and how the applicability of the document changes it's format:

a.) an advisor or consultant to you on your network, it's architecture  it's operation, etc.

b.) information security systems (EISS) or other  Corporate (internal) standards like  SOP or SIC

c.)  ISO9000, SEI  or other Auditor who will be assessing your site's compliance with external standards

d.)  anyone else (other site's network, systems, security admins) who might be trying to either help you with a  problem you're trying to solve or learning about a problem you have already solved.

Some assumptions:

I'll make some fairly generic, but I think fairly valid assumptions here :

  a.) most people who will read this document  (about how to document correctly)  are creating their documentation for one of the following reasons:

1.) their boss asked them to

2.) they must do it to comply with some internal or external standard(s) body (see items b & c above)

3.) they are trying to share information with others in their peer group (DIGs - for instance)

4.) they are attempting to give information to someone to ask for their assistance in solving a problem (or vice-versa

known informal audience (your peers in your work-group)

known, but more formal audience (your boss will give this presentation about your department)

un-known - informal audience (perhaps a paper about your work at a training conference

un-known - formal audience (perhaps a paper about your work at some standards body or at some public forum)

      a.) maybe their boss will pass it to his or her boss - who will pass it along to someone else  (implicit in this assumption is that the person ultimately reading your document may be totally un-aware of the reason you wrote it or the geographical / political / network / systems / hardware / software environment  in which you wrote it or for whom you "thought" you intended the audience to be?)

      b.) if you write something and send it to someone else to ask for support - they may send it to someone else (for further support) without your knowledge - and again - the ultimate receipient may not be aware of  the origin)

      c.) remember - also - that MUCH of what goes on in Asia - (in particular) is read by people who do not speak English (much less "American" English) as a native language.   One of Motorola's greatest shortcommings is that 98% of Motorola's standards documents are written by Americans, who not only do not know how to write "English" documentation but who have also never lived or worked in a country where the native language is not "American" English.

SO _ please - don't be like "Americans" in this respect. - Write simple English - for those of us who don't read English so well...
 

And think about the "permutations & combinations" that all those items listed above can take if you write something for one audience for a given reason, and it is used by someone else in a different context.

Four simple steps to Documentation Done Right:

1.) Consider the audience

2.) Consider yourself (as author) and the reputation that goes forth with your document

3.) Consider the subject you are representing

4.) Consider the timliness of your document

1.)  Consider the audience:
(both the one you know will read your document as well as the ones who will "possibly" read your document):

   several ways to do this:

     a.) write a brief section about "audience" - and the assumptions you make about what the audience's background and level of knowledge is about the subject you're considering

     b.) write a brief section about "background" - this is especially helpful when working on problem solving e-mails & documents, and might contain sections like:   hardware type, memory, hard disk, bios or ROM version; operating system version, configuration, applications loaded or version of problem application, etc. - there's a fairly obvious implication here - that is if you give the reader ALL the information they need 'up-front' - they're less likely to have to start a conversation with you or others - to get the problem resolved, but by putting the information in a section called "background" or "systems config" or something like this - the experienced - or secondary reader can skip -over the section and get to the real problem.

  b1.) you may also want to build another small section that has aspects of "audience" and "background" and that section would be called a "DOT" or "Definition of Terms" section - somewhat like a glossary - many would call it a glossary.   In most of the work & documentation that we do in Motorola GSD this is probably not necessary - However, remember that not everything we do, do we know who will ultimately read it.   Additionally, remember that sometimes there are some "local" names & terms we frequently use that may not be familiar with those that come from outside our local environment (pity those of us who come from afar, infrequently, and who can't remember you set of acronyms and separate them from those at the site we were at last week).

------

    c.) make certain that the documentation contains what I call (very bad name) "document documentation" - that is - somewhere on the document (or in the e-mail or on the PowerPoint presentation(s)) should be all of these key pieces of information:
 

Above all - ANY document should have:     
       the Document's "NAME" - what is this - ??? what am I reading about ??

and  it should also have most, if not all of these:

  a.) author's name & e-mail address (as a minimum)  you could also include phone / fax / snail-mail - etc. etc.)

  b.)  a version or revision number of the document

  c.) date (in a "dd_mon_yyyy" format or some other format that guarantees that the month & day will not be confused.

  d.) page number(s) (and "of   xyz pages")   if appropriate (obviously not appropriate in e-mails)

  e.) a "filename" - which is Not the Name of the Document, but where the document is stored on your file system

 

2.) Consider yourself - consider your reputation:

Perhaps this is why I see so many documents that have no author's name on them.  Perhaps people recognize they've done an un-acceptable job of documentation and don't want their name associated with the end-result.

If this is the case then you as a manager or employee need to ask yourself why you're documenting something.   Now I know that no Motorolan would ever feel this way.   But I also know that many people are not "documentation people" and therefore should not be forced into making documentation.    Documentation, on the other hand is a significant part of many corporate responsibilities, and as such - if we have employees in roles that require documentation but they either will not or cannot do an acceptable job of documenting their role, processes & policies then perhaps an alternative methodology  or employee should be considered.

Also consider the fact that many of the people in an organization that we will never meet or come into contact with will read our documentation and form an opinion about us.     Ultimately - those same people may be in a position to either make a decsion about our career or our promotional opportunities, and all we will have ever contributed to their understanding of us as employees and as humans is the writing we've done.   Think carefully about this as you fill-in your PACP.

Make certain that documents that have your name on them are worthy of that name.     Additionally - consider also that you represent your Motorola unit to both internal and external organizations when you write.     Make us proud to have you as an employee.

A sub-category here: -  Again - in the environment in which we work we are frequently required to engage in a bit of knowedge or time "re-use" by accepting "templates" from other organizations.    There's a lot to be said for this practice and a lot to be said for the value it has to the organization.     BUT _ if you put your name on a borrowed template and you do not  completely review that document, line by line, word by word for applicability to your situation, you could be (as the author of the "localized version" ) be very embarassed.

This is especially critical if the localized version is then sent to some standards or certification granting authority.

How embarassing to your organization to have  an Audit body come in and say,  "Let me see this document or log-file from 1992" and you to have to say, "We didn't even start our business until 1996",    because someone didn't completely review the template which had default 1992 dates in it?

                    Where does that leave your organization in the eyes of the standards or certification granting body?
 

3.) Consider the subject you're representing in your document:

Rember that documents covering items such as Information Security Audit Compliance, Disaster Recovery Plans, SEI & ISO Audit subjects, business plans, project specifications all these are both legal as well as business-critical documents and will be seen, read, reviewed and updated by a number of people after your involvement with them ceases.  Remember that standards-granting / certification granting bodies will also "periodically review" the status of the certification, and when they do (1-2-3years or more) down the road that you r document will most probably have to "stand the test of time" and continue to support & be valid for the purpose it was written.
In particular this is one place where having the filename / pathname inside the document can help

  BUT: _ remember - as time goes on and both project people and Systems Administrators change file-system-structures, it may be necessary to modify some of the documents in order to change the "filename" parameter inside the document as computer filesystem structures change & evolve.

Remember also that a number of these  (Standards Based) documents have their own form & format, structure and methodology that they must exist in.
 

4.) Consider the timeliness of your document:

Remember one thing - if you remember nothing else about documentation, when you create it.  It's much like getting pregnant - once it happens the future is an unknown - it's like "I've created this being" and now the world will do right by it or wrong by it. 

You turn-it-loose on society and it has to stand on it's own two feet, and it has to be "all it can be" by what you give it - by the love, care, thought, and tenderness you engender it when you give birth to it - after that - it's on it's own.  

So - best to be careful when you create it - because if it is to be successful in it's life (just like you hope your children will be successful) you must be thoughtful and creative to give the document the tools & knowledge to exist beyond you and in many cases without you.

One other thing about "timeliness" - when you leave (which you ultimately will) your organization - someone else will fill your role.  When that happens and sooner - or - later someone will come along and say "I need a copy of George's DocumentZ" - it's a lot easier to trace where that document is / was / should be if everyone knows that George wrote it - rather than it was just called "DocumentZ".   So this is a help to those who will both exist without you in your absence, as well as those who might follow in the footsteps of your role.

a few examples:

(from above: _ document documentation) some reasonse you might want to consider both yourself & the timliness

  give the reader a chance to come back to you, if necessary, to further discuss the subject

  give the reader a chance to contact you about further work in the area

  give a reader the opportunity to get you to help them with similar work

  give a reader options to pass along your wisdom to someone else they're trying to help.

Frequently we start-into a documentation project with this mental image of what we're attempting to say, without much thought to those items discussed above.   AND - when we do - and we get 1/2 way through the document, and get interrupted, go to lunch, spend a weekend snowboarding or windsurfing, we come back to the document without the energy, focus, and discipline we first started into the project with.

When that happens both our ability to express suffers, as well as the reader's ability to comprehend the document both as a whole as well as  the individual parts by themselves.

There's an extremely simple way to avoid this pitfall.

       An outline will help you keep both your thoughts & the direction of the document "on-course".

It's as simple a step as taking as little as 30-90 seconds before you start-in to write down 5- 10 lines of text that specify your main points - just to give you an example here's the  vi file that I created that outlined this document.

I think if you'll try this on your next few documents you'll be surprised at how much it helps you..

   "Try it, you'll like it!"
 

Summary: - - - -

  What I've tried to share here is the accumulation of many many years spent reading documentation written for various purposes & audiences.   I'm not going to be egotistical enough to claim that I know everything, however I will say that I've read enough, - in enough different circumstances, to know what most auditing / certification / qualifications bodies generally want in order to grant that "priveledge" of whatever.   Additionally, I think many e-mails and DRPs / Backup Plans & other such documents can well benefit from a bit more "structure".     Lastly - in my role with GSD in the last three years, I've seen a lot of systems Admins come & go, and a lot less Systems Admin Managers come & go, but I am continually frustrated that the documentation that should outlive many of our lives doesn't seem to be well enough documented to live a life alone without it's creator.   I think we could all do better in making our documentation one of the "legacies we leave behind" in terms of the Motorola Totality of Leadership requirement of "legacy"...

I leave you with the hopes that your documentation will soon "make you proud" and that readers will honor and respect you,  after they've read what you've written,  years after you've gone.

Good Luck! - write-on!