// archives

Documentation

This category contains 15 posts

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 […]

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 […]

Strict Rules of Golf – for IT

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 […]

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 […]

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 […]

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 […]

Location, Location, Location: Terminology Confusion in ERP Projects

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 […]

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 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 […]

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 […]