Documenting Processes...

To my readers, I have spent a long time refining my own processes, and now I’m trying to come up with a standard way to document it.  I’m going to suggest a standard documentation practice, and ask for insight and considerations in the comments.  Like any process, or method I follow, I’m open to criticism and suggestions.  Things work best when more than 1 mind is involved.  Too many things in this world are of sheep.  Once something is created, all the sheep follow.  Don’t be a sheep, comment on this.  :D

I recommend using a Wiki, and that each part of the process be its own document.  Now, I’ve worked for lots of different companies as a contractor, and have seen many good and bad practices.  Ultimately it comes down to usability.  If the people can’t or don’t use it, it won’t matter.  All documents should have 3 directives, if and when possible.

1)      Keep things clear. 

a.       Do you get the point of it?

b.      Is it confusing? 

2)      KISS (Keep It Simple Stupid)

a.       The more specific something is, the less it can be applied, and therefore, the less it will be applied/retained.

3)      Keep it short.

a.       I’ve worked at a company that there entire process was clearly defined, with around 8000 documents.  Each document had an average of 5 pages of explanation, and it often took 10 minutes of reading to understand the basics of it.

b.      Take your most vital and basic explanations and put that at the top.  Then, if more space is needed, Re-iterate at the bottom.  Most people don’t need to know the details.

c.       This does not mean to cut out necessary information, but simply to allow the fastest use of it, and more info when needed.

My general structure would follow this means:

1)      Include the documenting style

a.       If the style changes over time, this will let you know how this was intended to be displayed, for past editions.

b.      This is a reference to an explanation document that follows the same format that it describes.

2)      Give it a short/clear sentence for a title.  It should include key words.  Less than 80 characters if possible.

a.       This is the document title for links, or the file system, as well as a headline/title for the page.

3)      List the exact steps that are the same as often as possible.

a.       This should be bulleted and short, anywhere from 1 sentence to 8.  If it is more, consider whether it should be split into more process documents.

4)      List Prerequisites

a.       This should either be 1 line explanation of what was needed

b.      Or it should be a link to another process, that always needs to precede this.

5)      List Follow Ups, which is just like the Prereqs, except that these are things to do next.

6)      Optional references. 

a.       This is where links go that you do sometimes.  List the most obvious condition(s)

7)      Detailed statement of why this is being followed.

a.       This should be a bulleted list,

b.      Each Item should include sub items that either defend or challenge it. 

c.       This should be open to being challenged by anyone,

d.      Challenges should not be removed.

                                                                           i.      They should include the reason they are not following this.

e.      If need be, this section should become its own document, if there is too much explanation.

I like the idea that all reasons are defendable, and if we *have* to support something that we challenge, we should know why.  All politics should be stripped from this.  Only fact, and purpose.

Another thing about this is that for some projects, a area of the general process documents might not apply, and may cause undue stresses and difficulties.  In those cases, the project should include a document outlining the needs for a change, including the process (in the same format) of what they are changing and following the same model for giving supporting reason’s and challenges with it. 

Finally, This needs to be flexible, and ANYONE who works with this process NEEDS to have the right to post challenges.  Things change, better ways might be found, and this allows the processes to grow over time.

To recap: This is an initial draft for how to document.  It follows many standards that I have seen succeed, particularly in the areas it was best suited.  However, I am one man, and one island.  No general process should be made by me, or anyone, alone.  

By all means, post any ideas or concerns.  :D