Back in March I took part in CCATP Lite #675 about working from home, along with Allison and the pod-daughter, Lindsay Tondee. We had so much fun discussing our different experiences that there was a whole section of content I had notes for that we just didn’t have time to get into. I’d like to cover that now. The topic is non-real-time communication.
I think I mentioned in CCATP that one of my driving forces for the way I work is being lazy at heart. If I can save people having to bother me, I’ll put in the work ahead of time to ensure it is so. Occasionally I have the opportunity to teach, which is something I really enjoy, but more often there is simply not time, or sometimes no inclination, to properly teach a topic. At these times I turn to the next best thing — documentation.
I used to have an attitude common amongst technical staff — “I can either document it, or do it.” Two events happened that turned me away from that way of thinking, and they happened in the same job and a couple of years apart.
It was 1998 and I was working for a large multinational company with my chief focus at the time being the introduction of a new software tool into our development team. When I say it was my focus, I mean it was my responsibility. I and my team had put a lot of work into figuring out configurations, extra tooling, processes, and more, and we were piloting the results with one project within the development team.
Things were moving fast. Things were breaking. Despite some initial training, developers and testers alike had lots of questions. We noticed the same questions being asked over and over so we started writing an FAQ. This had a positive effect but still people would turn up at our desks, FAQ in hand, seeking clarification or the answer to something not in the FAQ. We constantly refined that FAQ to address more and more of what people were struggling with. It started getting big, but it was working. Or was it?
One day, just after a developer had left my colleague’s desk, FAQ in hand, he turned to me and asked “Did you see that?” My puzzled look prompted him to expand. “His FAQ was a really old version!” We’d built our FAQ in Microsoft Word and we made sure to put the date of last update clearly on the document, but the nature of such documents is they get passed around from person to person and, worse, printed.
Not getting the document from source is a problem, but printed documents are worse. They are quick to reference, but are out of date as soon as the toner hits the paper. It didn’t matter that the date was there on the front page, because the front page was folded behind the rest as it sat on all those desks. Our constant work to revise and expand the FAQ was somewhat in vain. We needed to address this problem — for the benefit of the development staff, but also for our own sanity.
The company had recently rolled out Lotus Notes and we realised it would solve the problem. We built a Notes database which was a simple, categorised list of questions. When the user clicked on a question, the answer would be revealed. We had essentially the same capabilities as Word, including screenshots and marking up standard terms, code, commands, and more to aid in legibility. We quickly converted the contents of the Word document into the database and then went around everyone’s desks confiscating their printed copies as we explained the new tool and showed them how to use it. Our support burden went down literally overnight. Everyone had easy access to the latest information with a few clicks.
This lesson didn’t really sink in for me until the next event occurred two years later. I had been a self-employed contractor at the company for four years but management were souring on this long-term contracting concept and I was tipped off one day that my own job had been posted on the company job board as a vacancy! I applied and, astonishingly, I got the job. My job. I was now a permanent employee.
Not much changed on a day-to-day basis, but there were certain requirements as an employee, one of which was that I have my Personal Business Commitments formalised and on record. (Anyone who worked at the same company is now sure they know who I worked for.) I sat down with my boss, who I knew well, to discuss these and I cheekily offered this appraisal: “Let me guess. My commitments are your commitments and yours are your boss’s and theirs are their boss’s and so on, and none of it means much except ‘do what you’re told.’” Without a flicker of emotion he replied: “Essentially yes, but I’m adding an extra one just for you.”
His new commitment for me was very simply expressed. “Reduce the team’s reliance on you being here.” I was, by that point, the senior member in my team — mostly through attrition — and had recently been overseas for several weeks at a time, working at other company sites. I asked how he thought I was going to achieve that and his reply was equally simple. “I don’t know but you’ll have to work something out.” Spoiler alert. I did.
It didn’t take me long to figure out that our pilot FAQ held the answer. Not literally, but in its very existence. What if we had a team FAQ as well? A place where the whole team could distill their knowledge in such a way that it became every other team member’s knowledge as required. The pilot FAQ had since become a ‘production’ FAQ as we had rolled out the database to everyone, and it had grown a lot. As such, I found it a bit unwieldy, so I set about building the team FAQ a little differently.
I discovered with a little tinkering, that a Lotus Notes database could act like a web site. I built out a front page with links to a series of categories, each of those being a page of its own and each containing links to further pages with the actual content. The real power came in those content pages where further links could be included to related pages. From this I developed a simple approach to writing documentation most efficiently. That is, efficient to write and efficient to use.
These were my rules:
Never write anything in more than one place. If you had to do process A before process B, then the process B page should mention this fact and contain a link to the process A page and not a duplication of the same steps, no matter how simple process A was. This meant if process A ever changed, it only needed to be updated in one place. For simpler processes that are used in a lot of places, this saves an enormous maintenance burden.
Write for the correct audience. While our project FAQ had addressed an audience of developers and testers, our own team database — which we called the Team Knowledge base — could be a lot more technical at the operating system level, and could assume certain knowledge that developers and testers would not have. Writing for the correct audience is most efficient.
Use numbered steps for processes, but not ONLY numbered steps. Numbered steps are incredibly useful for following an unfamiliar or complex process, but those steps should not be a simple sentence or command. They should spell out exactly what to do. And they should follow the next rule.
Always explain WHY. Have you ever tried to follow a process only to find out part way through that something it said would happen didn’t happen, and now you’re stuck? I have, and it can be infuriating. If the process explains at each step why you should do what it says, then you have a fighting chance to work out what is different and proceed with the rest of the process.
Test the process. A process is only of any value if it works, and that means it needs testing. You can run through the process yourself but the ultimate test is to get someone else to do it. Preferably someone who doesn’t know much about the topic. There was one memorable process in our knowledge base which showed the power of testing. One member of my team had developed a very complex process which no-one else in the team had any idea how to do. Including me. I pressed him to write up a process but he was extremely busy. I eventually got a rudimentary process out of him and then asked a whole bunch of questions. From this I wrote up what I thought was a proper version of the process. On my first test I failed dismally. More questions ensued until I finally thought I had a handle on it and I updated the process to what I thought must be near complete. I then handed it to another team member and asked them to have a go. More questions, more updates and they got through the process. Then I handed it to yet another team member. There were seven members in my team including me, so that’s five people not originally involved in writing up the process. I gave it to every single one of them to run through a real task and the fifth and final person gave me back the printed copy I had given them (there was no access to the electronic version where it needed to be used) with a single markup in red pen where something I had said would appear was not shown correctly.
And the final rule, if you see an error, correct it. Updating the process during the testing phase is vitally important, but that should not be the end of updates. Processes, tools, requirements, and more all change over time. Sometimes even the most comprehensive testing can still miss things. This final rule is what stops the knowledge from becoming obsolete. It’s also the rule that keeps people using the resource. It doesn’t take long for someone who keeps finding the information wanting to stop using it altogether. Conversely, I have found that keeping things fresh not only ensures consistent use of the resource, it also encourages others to make their own updates when they see issues.
There is one other thing I didn’t make a rule but which is definitely worth considering. A common phrase is “Don’t let perfect be the enemy of good.” The example I described above was certainly the only process in our knowledge base that got that level of testing. Some processes weren’t everything they could be, but they all worked. There is also a saying “Something is better than nothing.” There is value in a “knowledge dump” — where someone quickly pastes in some notes with the intention of later fleshing it out into something more useful.
Everything I have described has focused on processes but there is another class of information which should sit right alongside these. The team knowledge base I built formalised the two types as “Process” and “Reference” pages. Reference pages did not describe how to do a task but rather how a particular tool or technology worked, how it was configured in our business, or a list of tips and techniques. These reference pages were often linked to from process pages and vice versa. This was a big help with the why rule in process pages, and when looking at a “how it works” reference page you could quickly go to related processes to see how it was used.
A year after that sit down with my boss, he agreed I had achieved my objective. I had absolutely reduced my team’s reliance on me being there, and this was illustrated perfectly with another overseas trip I did a few months later. Upon my return, I asked one of my team members — my official stand-in while I was away — how things had been in the three weeks I was gone. His response was “All fine, but we weren’t sure about this…” They had kept one single issue for me to address when I returned. And it wasn’t anything urgent or terribly important.
I have since built, deployed, and championed knowledge bases in two subsequent roles and my team today is fully on board with what we call our wiki. Though originally built with wiki software it now resides in Microsoft OneNote which, like Lotus Notes, allows a locally stored and regularly synced copy. It also has a very useful feature in that it highlights pages that have changed since you last visited them. This enables me to see just how many updates my colleagues are making. It’s sometimes hard to keep up.
The real value in our “wiki” is realised when team member who is on call gets roused at 2am on a Sunday for an issue, and effectively has the entire team’s expertise on hand to help resolve it. Often during work hours one of us will utter the phrase “put it in the wiki” when something is discovered that isn’t already covered and every time it appears there in short order.
I have come across people during my career who think this free giving of knowledge is a bad thing. They believe that holding the knowledge makes them indispensable. I have also seen that this is simply not true. When it comes to downsizing, rightsizing, restructures, or whatever you want to call it, held knowledge doesn’t seem to be a huge factor. Instead, people who have experience are valued more if they willingly share it. Despite my earlier comment about laziness, it can actually be hard work to create good documentation but I believe that sharing information gives everyone the best outcomes. Information you impart freely will unburden you from being “the expert” all the time and if everyone pitches in — the whole becomes greater than the sum of the parts.