More Thoughts on Why Techs Don’t Like Documentation

A few years ago, I was interviewing candidates for a systems analyst job, and trotted out one of my standard questions: Tell me something you have done that you are proud of. This particular developer called out her source code annotations (comments), and was rather specific about her own comment quality standards. But when I asked her if she likes to write documentation, she was quite hesitant - and that surprised me a bit, made me think. What's the difference…

Why Bother Documenting My Solutions?

Interesting line of conversation around an internal Help Desk project ... "What exactly is the point of my help desk ticketing system?", posits the hardy IT Tech. "I, like so many other IT technicians, am expected to solve end-user problems quickly with my infinite knowledge of every potential PC / software combination, not to mention a dizzying array of specialty printers, alternative input devices, smartphones, and tablets. And I, like so many other IT technicians, realize that the most capable,…

Strict Rules of Golf – for IT

6 January, 2014
Documentation, Web 2.0
0 Comments

Years ago, an avid golfer told me about his long-time buddies who, after a few years of playing together, found themselves getting into arguments during play. Through high-school and college, they had been fairly competitive and loved a friendly wager, but they got better as they got older. The money started getting serious - and the squabbles took away from the fun. So they adopted a new Guiding Principle, and began to play strictly according to the USGA Rules of…

Introducing Collaboration Tools? Three Required Personas for Success

When introducing collaboration tools to an organization - creating the corporate intranet, defining project sites in Sharepoint, etc. - there are multiple skills you must master - well, at least get better at. You need to capture the ideas and communicate the data such that your target reader understands what you are trying to convey - but you also have to help them locate it in the first place. Three personas you'll need to adopt, three sets of skills to…

How to Draw an Owl

On Documentation One recent afternoon I found myself in deep conversation with potential consulting partners, holding out for a difficult requirement: "Excellent Documentation". That's a tough one to quantify, let alone describe; why hold out for something at once critical and ineffable? Doesn't every project talk about the importance of providing documentation, yet rarely deliver it? Don't most people flip past the pages of detailed work process, going right to the keyboard to bang away, expecting tool tips and intuitive…

Technical Debt and the Cost/Benefit of Knowledge Retention

A rather rigorous, Financial-sounding title for a high-concept line of thought ... Thanks to Jeff Atwood at Coding Horror, for calling my attention to this article by Martin Fowler on Technical Debt: Technical Debt is a wonderful metaphor developed by Ward Cunningham to help us think about this problem. In this metaphor, doing things the quick and dirty way sets us up with a technical debt, which is similar to a financial debt. Like a financial debt, the technical debt incurs…

Location, Location, Location: Terminology Confusion in ERP Projects

11 April, 2009
Documentation, ERP
1 Comment

Have you ever experienced the clash of terminology that results when supply chains are brought together, due to acquisition or merger? The typical scenario: different groups using multiple terms to describe where product is manufactured at and shipped from; folks use terms like "location", "plant", and "site" interchangeably, and confusion can result - are we talking about SAP configuration? Wide-area network architecture? Rollout plans? To communicate effectively, it helps to clarify things. Here is a starter list of terms from…

Zodiac of Knowledge Capture

The start of a new year gives me a rare chance to measure my knowledge capture output over time. I maintain electronic journals for the various projects I am driving, business units and functional areas I support, and people I work with. This results in a hundred or so separate MS Word documents, with generally the same format - still, it would be quite tedious to take a word count each week to check my output. However, at the beginning…

The Power of Paper in Business Communications

Confucius was wrong - it is good to live in interesting times ... I'm deep-diving into a number of projects at work, while juggling a sudden surge in business travel (the majority of my tweets of late). All of the work involves significant change - different tools & process, or reworking process "traditions" that have ossified over multiple years and a succession of owners. I have developed a stack of notes on a range of topics - excellent blog fodder…

Best Practices for Process Documentation: Iterations (2 of 3)

Last time, I wrote about checklists, and showed the example of the B-17 preflight. Simple, fits on a single page, and hits all the critical steps, in just the right amount of detail. Plenty of processes in the IT department are made That Much Better if they are accompanied by detailed, effective Process Documentation. Of course, that's all motherhood and apple pie - everyone agrees that the existing checklists are great. But how do you get started? I mean, assuming…