Posted by: Jeff Timmins | October 25, 2010

Elements of RM – Documentation Part 1

The exciting thing about Release Management (RM) that there are a number of parts or elements or the work.  Thus to be effective in RM you need to be a semi-expert on multiple topics.

There is no “love” for documentation as it either goes unnoticed when done well or highly criticized when done poorly.  Still, without it there are no guarantees what was tested will be actually installed and the Production staff would be left to guessing.

Below is the first entry on documentation:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Goals & Theories of Update documentation

  1. Just enough – detail is great for Production update notes but too much then important information could be camouflaged, use “see XYZ for details” when needed to keep it simple
  2. Write to your audience – know who will be using your documentation and then write to their level as this helps keep the clutter down
  3. Be consistent – create a writing style for your documentation and stick with it (if you don’t like your style borrow one for someone else)
  4. What the customer wants & needs – customer is always right so give them what the want.  If the boss wants something else then either create a sub-set or super-set of the documentations or form a compromise.  In the end, no customer will use something if it doesn’t fit their needs
  5. History is best remembered when their are notes – if done well, the documentation of the update can be used in the future for an easy reference about what has changed in the past (always good when researching the source of an issue)
  6. Centralized location – anyone wanting information about a Release should never have to wonder where it is so keeping a single location for documentation is critical
  7. Find a Reviewer/Editor – always a good idea to build a relationship with someone who’s writing you respect
  8. Test it – documentation should be tested in Pre-Production just like code, without testing Risk increases

Important categories to include in Update documentation

  1. Title, Version & Date – sounds basic but always a good idea to standardize title of update, the version of the update as well as the date of the update document
  2. Introduction – High-level Process steps & Changes in the Release as well as the Package location (new features, config files changed, known issues, Microsoft Updates supported,
  3. Before the Update – Steps to be taken when system is Online to prep for update (backup, copy files to update location, config files to copy in, etc.)
  4. Update Process – Steps to be taken for the update when system is Offline
  5. Post Update – Install validation, Smoke Test, Support Validation, Production Hand-off
  6. Appendix – Location for details that would otherwise crowd above sections like known issues, definition of application switches, config file examples, documentation sources and other details.

As I exit today I’ll leave you with some thoughts from Jacob Kaplan-Moss’ Writing great documentation which focuses on Developers writing Technical information.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Categories

%d bloggers like this: