As a Seattle IT Consultant, I review a lot of documentation.  Not because the clients I work with have documentation, but because I am training technicians to write their own documentation for the first time.  Documentation is one of my favorite subjects.  I think that a technician can increase their income faster because they are willing to do what most IT experts seem unwilling or unable to do.  It takes time to get better and I often feel like an English teacher.  Recently I have been working with a client building a knowledge base for Tier 2 and 3 technicians.

Here’s an example I’ve run into on several past Fortune 500 companies.  Tier 4 technicians solving the same problem over and over again.  Tier 4 technicians or problem managers if you go with ITIL definitions, should only be troubleshooting Unknown issues.  So if they are troubleshooting an issue they’ve seen before, there is a problem.  Now the owner is paying for root cause analysis on the same issue four or five times.  For one of my clients it was actually 1000′s of times each month.  The problem wasn’t with the tier 1 technician.  It was with the lack of documentation by the tier 4 technician.  Once the tier 4 technician understood the problem, a KB article should be written for the tier one technician so the tier 1,2 or 3 technician can solve the problem in the future.

By writing “How to…” documents the Tier 4 technician can teach the tier 2 and 3 technicians to solve problems before they become tier 4 issues.  Here’s a very high level layout for a how to document.

Simple Outline for writing a “How To…” documentation

Body Section 1

Define the problem <Documents that fall under the “How to…” Describe the steps for accomplishing tasks as simple as setting up an email account in Outlook or as complex as installing a set of servers.  The first Section in the body outlines the problem and high level steps for solving the problem. In this first section outline the prerequisite, the audience and other issues the reader might need to know before starting the process.>

Body Section 2

<In the second paragraph outline a high level process.  Advanced audiences will be able to pickup the solution without reading the detailed instructions.>

(Note: Mistakes many technicians make Not understanding the needs of their audience Not formatting the steps in a clear way Assuming that the reader knows as much as the author)

Body Paragraph 3

In this section the details are written out.  Writing documentation in High level steps is much simpler for advanced readers.  Then indented below each high level step, giving further instructions for completing these high level steps

Example:

Summary description

Detailed Description

Step 1: High level description

Details to accomplish step 1

Step 2:  High level description

Details to accomplish Step 2

Conclusion

Technician’s notes:

By creating High level steps, if the technician already knows how to do the step, the technician doesn’t have to read the details of the step and can move to the next step.  Technicians that need the details can run through all the steps.  For an outline go to Seattle IT Edge.info

Check out this site for layouts you can copy to document your own network.  If you need someone to create a knowledge base for you check out, www.irrevo.com.   I am creating a list of document descriptions you’ll need to document your systems including, How to…, Settings, Topology and other documents you’ll want for your network.

When I started my IT Career I heard this joke about developers…,

…A team of IT experts/developers are sitting together in a room bragging to each other about their skills.  Then the phone rings.  The head developer picks up the phone and talks for a few minutes.  Then hangs up the phone and says to the group, “That was the boss; he has a new software project for us.  You guys start coding; I’ll run upstairs to see what he wants.”

At least I thought it was a joke.  Too often working with software development teams, IT experts and even for managers this is the exact scenario I run into over and over again.  There’s this idea that we need to start getting something done before we know where we are at or where we are going.  What happens a year later we hear the lament,

“If I knew now what I knew then, I would have done it completely differently, but now it’s too late.”

Long before there was a PMP certification, Agile or Scrum we were developing strategies for avoiding these types of “cart before the horse” problems.  I’ve found that the first successful step is a strategic Assessment.  I outline this in my planning process on my site.

I like to think of a project like a walk through a dark crowded forest.  (I probably read the Hobbit at too young and age and it has affected how I think about these things.) If you had a map of the forest you would need to identify two things before you find a path.  You must understand “Where you are at” and “Where you want to go”.  The strategic assessment identifies where you are at today.

I’ve noticed that lots of developers prefer to start over from scratch.  Especially when working on a website.  I know that building a Network for the first time is similar for the infrastructure expert.  I think this is because when there is nothing, we know where we are at today.  We are at ground zero.  We have to build something from scratch.  As the business grows and the network grows, networks become convoluted.  So without a good change control process, most IT groups have no idea where they are starting from.   When looking at a map, it’s obvious that in order to create a path from point A to point B, you must know where point A is.  Yet IT experts seldom know where Point A is.  So when trying to get to Point B, they miss steps.  These steps become problems that haunt the IT department for years.  Unfortunately if the IT department has no idea where they are at today, they have to admit this to management.  Admitting this to anyone means admitting to fallibility in the minds of some IT experts.  Instead these experts start “coding” like our experts in the joke.  This gives the impression that they know what they are doing.

Just as important as knowing where you are going on a project is knowing where you are starting from.  “Winging it” means that you really don’t know where you are starting from.  For the client this is going to be wasteful of the time and resources while the IT team tries to figure out where they are going.  The strategic assessment becomes the tool for identifying where you are at today.  Consultants like me, work with IT departments who have never done a strategic assessment.  It often puts us at odds with IT departments.  I would recommend to any IT expert, to develop an IT assessment process.  This way when the IT consultant is brought in, it’s only a verification that you do know where you are at

Planning

If you’ve worked in the IT world for any length of time you’ve implemented technology.  If you’ve implemented technology you probably know what it’s like when things go wrong.  Two or three hours on a weekend can turn into 48 hours of sheer terror.  To avoid the terror, planning is the key.  Many IT technicians think they are pretty good because they have successfully followed a set of directions or a wizard.   The reason they are so successful is because of the planning that went into creating that set of directions or that wizard.  The modern network architect needs to not only know how to follow directions, but also how to write the directions.  When the directions fail, the team is in for a long sleepless weekend.

Imagine that it’s Saturday morning you’ve started working on the upgrade since 6:00.  You’ve run into a few problem and you think you’ve just about got it.  A call interrupts your concentration on the problem.  It’s your significant other asking if everything is ok?  You had predicted about 2 hours to complete your work and it’s been three.  Not a big problem but this is definitely taking longer than expected.  You predict another 30 minutes.  Four hours later another call interrupts your concentration.  Again your significant other asking how things are going…??  This is how the rest of the weekend goes.

In the beginning of my IT career this was the way many of my weekends went.  Luckily technology was not complicated back then and I learned a lot over those weekends.  As the technology and infrastructure became tougher and more complicated whole teams of IT professionals would be having the same calls with the significant family members waiting at home.  Most of the time, our loved ones began recognizing the cycle and stopped believing we’d ever come home.

A successful weekend project is about planning.  Then testing the plan and fixing the plan until we get it just right.  In the early days we could work after hours or on the weekends.  Now with international teams there are times of the day when it’s impossible and other times of the day when it’s almost impossible.  Over the years though I noticed that my projects were getting less and less crazy on the weekends.  I wish it was because I could say that I was a better technician, or incredibly experienced.  The reality is that I was just becoming more organized.  One of my technicians summed it up by saying, “James I like working on your projects, because the instructions are so clear, nobody can make a mistake.”

With experience comes wisdom.  Get hit over the head enough times and you remember to duck the next time.  Here are some of the pitfalls I’ve found that plague weekend technology work.

Poor technical directions – So if you have a team coming in for the weekend, how much do they know about the project you are working on?  Most project managers have been thinking about the project for weeks, months and even years.  For the technical team this could be the only time they’ll be working on the project. 

Complete Documentation – Writing bullet proof instructions for the team members is an art form, but it means they make fewer mistakes.  The team will just run through the instructions, and then they are done.  Documentation for many projects is non-existent.  So technicians begin making mistakes.  Time consuming mistakes that you, the project lead, will be required to troubleshoot and fix.

No Testing of process – How often have you tested your own documentation?  Every time I walk through a process I learn where I made a mistake in documentation or in understanding the real problem.  Every large implementation has at least one test environment to simulate the problem.  Every project lead should be testing the weekend process in this environment.

Forgetting about the details – I was working on a project in Los Angeles California building out a small server room.  Suddenly we were stopped because we had not included patch cords for the servers.  I am a Seattle IT Consultant not an LA IT Consultant.  I know all the vendors in Seattle and the fastest routes to find them.  It seems silly in retrospect, but we hadn’t even planned in the costs associated with the patch cords.  It just seemed like a detail that would take care of itself.

If you’ve ever dealt with LA traffic it can take an hour just to drive to a store that carries just what you need.  So purchasing the cabling, the driving etc. took ½ the day waiting on congested freeways.  Imagine our frustration after our first trip when we realized some of the cables were too short.  Which meant another two hour round trip drive for more patch cables.  A week later we had taken at least one trip a day for small details we had ignored.  To this day I associate patch cables with traffic congestion and a symbol of unplanned expenses.

The first time I started using Microsoft Project, I finally began learning about how to track the details of a project.  An application like project allows tracking of each step between each milestone of every project.  Then by analyzing the steps you begin to see and list dependencies and then prioritize each step.  Finally dates and time can be associated with each step and the calendar can be accurately predicted.

Over time I began to realize that my portions of the projects were no taking any time at all.  Not because they weren’t complicated.  Rather because my projects were well planned with contingencies and roll back planning.  People wanted to work on my projects because they knew we would be waiting for the other projects teams rather than feeling the stress knowing that their team was holding up the project.

I’m curious to hear what other aspects of planning may have helped your projects.