cazh1 » Documentation

Introducing Collaboration Tools? Three Required Personas for Success

Jim MacLennan — Fri, 18 Nov 2011 03:25:36 +0000

An early SharePoint cert test

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 master, if you want your stuff to be relevant and get read …

Librarian – Where to start with a big pile of information that needs to be captured and categorized? Consider the typical technical tome – when browsing at the bookstore, how do you pick the one you will buy? I will select the winner by browsing the table of contents, to see how the subject matter lays out – very important stuff. But how do you end up using it? More often than not, I keep going back to the index, to locate a specific word (topic) and find out where the author has stashed the details. The Librarian should know the vocabulary in the book and the surrounding / related areas of knowledge, and fill the index with the key words and phrases that folks keep coming to the information desk to ask about. Sure, most word processors will automate the pagination tasks, but there is some skill and art in choosing the right words – and making sure the document contains those words in all the right places.

Experienced authors who rely on the index to function as their “local Google” will go back to the text and place key words in all the right places. Savvy intranet content producers will anticipate the searcher’s keywords and make sure they are in the document and/or the metadata.

Marketer – There’s more to it then just anticipating the reader’s needs. It’s not enough to write effective prose – you need to create content that wants to be found. Attack the problem like an SEO expert; learn how the search engine indexes content, and what data and metadata gets scanned. The Marketer will understand the local lingo and style of describing things, and make sure to include those words and that style in the text. Be realistic and humble – the vast majority of the planet does not actually think exactly like you do. Think about how you search for stuff on the internet, but also work hard to observe and learn how other folks find and absorb new information.

Completing the document is not enough – success is only achieved when people are actually reading and understanding the material. And they have to find it before they can read it.

Coach – You can document and publish plenty of material, but unless you get folks to actually change their behavior and use the tools, it will sit their like those big fat binders from long-past meetings, lovingly put together for the big event but now gathering dust on the bookshelf in the corner. The key is to find the opinion leaders, the folks who set the standards for the group – and give them extra attention and detailed, task-oriented coaching to change their behavior. Target the experienced hand, the one that folks like to emulate, possibly the one who can dictate the team’s behavior – and get right on the keyboard with them, helping them learn how to use this stuff.

This approach clearly will not scale to a large, geographically dispersed team; but if you can Coach the team leader(s) – teach the right skills and set the right expectations – the rest will follow.

Questions? Comments? Suggestions? Send mail to webmaster at cazh1 dot com
© Jim MacLennan for cazh1, 2011. | Permalink | One comment |
Post tags: coach, Collaboration, collaboration environments, collaboration tools, Documentation, empathy, full text search, Google, intranet, Knowledge Management, librarian, marketer, SharePoint, table of contents, taxonomy, team leader, teams, workgroup

All articles, blog entries, and other content on this site are licensed under a Creative Commons License

How to Draw an Owl

Jim MacLennan — Wed, 16 Nov 2011 03:27:41 +0000

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 UI to guide them through? Aren’t most technical teams passive-aggressive on documentation, procrastinating until the final week, throwing something together that the project manager probably doesn’t have time to read and review?

Click on the picture to check it out in book form ...

Still, I will press on candidate firms that want to code/configure for me, to put their manual where there mouth is, and show samples of the documentation that truly allows me to become self-sufficient. Many will piously claim an ultimate goal; to walk away from the project and customer [me], leaving me fully trained and self-supporting – even though [he cynically observes] they are incented to maximize billable hours. (Yes, I know the real truth; consultants enjoy the “fun stuff” – coding from scratch / developing new. Maintenance, extensions, and bug fixing gets boring.)

Of course, the more thoughtful Business Development folks, having been through similar conceptual wringers, will point out the difficulty of quantifying “acceptable”. But it’s not difficult to visualize; like certain non-fiction books, the really well-written ones where structure and prose come together in a perfectly natural way. “It’s like God wrote that”, I like to say, “it couldn’t have been written any other way.” Sort of like the Potter Stewart Pornography Test – “you know it when you see it”.

On Books

This turned the conversation towards books in general – fiction or non-fiction, read for enjoyment only, without regard to platform (paper or plastic). In fact, this is a terrific interview question I like to spring on folks – What as the last good book you read? It’s interesting how often the technical folks respond with Kernighan and Ritchie or the Gang of Four (no no yes), but I really like to talk to folks who want to review the latest pulpy summer fiction, interesting history, or a real brain bender like Hofstadter or Kurzweil. This is a great way to get into how people really think – listen to someone get animated about arcane topics like how to measure things – really big things, conceptually impossible things. You can hear it in their voice, see it in their body language – and it’s this honesty and energy that you want working for you, on the project or the contract …

Back to the Documentation

… and that’s probably the best way to identify an excellent documentation writer – do they get excited and animated about the craft of good writing. Do they know it when they see it – and can they identify why it works for them?

In the end, I agree that this is my white whale, a recurring windmill against which I tilt. Why do people overcomplicate the pictures and the prose, and create confusion out of something straightforward? Is it lack of complete knowledge about the subject matter – or lack of ability to communicate complexity with simplicity?

No easy answers here, and we’re running out of our scheduled time. To help make my decision, I’ll ask for samples; I find the best way to request representative work is to ask for something that the candidate is “proud of”.

Epilogue

An excellent quote near the end of this conversation; “I don’t read manuals … I clunk, I’m a clunker … I Apple” [emphasis mine]. Fascinating how intuitive usability has made a verb out of a brand name and a design philosophy.

Questions? Comments? Suggestions? Send mail to webmaster at cazh1 dot com
© Jim MacLennan for cazh1, 2011. | Permalink | One comment |
Post tags: analogies, Apple, communication style, creating understanding, Devil in the White City, Documentation, Hofstadter, Kernighan, Kurzweil, process documentation, Ritchie

All articles, blog entries, and other content on this site are licensed under a Creative Commons License

A Hierarchy of Information Requirements

Jim MacLennan — Mon, 10 May 2010 02:24:29 +0000

It’s a common problem statement – ‘I don’t have enough information to (run my business unit, manage this process, identify opportunities, etc.)’. The solution designer, when faced with a question like this, starts with a little detective work; the problem is too broadly stated.

This part of the project is itself an example of the problem – “I don’t have enough information to define the problem of “I don’t have enough information to …’ “

And, after a little detective work, we will probably find one or more of the following is correct:

The information [to run my business] does not exist (KM, BB)
The information exists, but I do not know that it exists
- I am unaware that it exists (KM)
- I suspect it exists, but I do not know how to find it (KM)
- I suspect it exists, but I cannot find it (KM, BB)
The information exists, and I know that it exists, but I cannot access it
- I am prevented from access due to security requirements (BB)
- I have no data access tool (BB)
- I have a data access tool, but I do not know where the data source is and how to connect to it (KM)
The information exists, and I know that it exists, and I can access it, but I don’t understand what I am looking at
- I do not know how to use the data access tool (KM)
- I know how to use the data access tool, but I do not understand the domain / terms / concepts (KM, BB)
- I know how to use the data access tool, I understand the domain, but I do not understand the data structures (KM)
- I know how to use the data access tool, I understand the domain, but the metadata is confusing (KM, BB)
The information exists, and I know that it exists, but I don’t want to access it – I want my team to access it, and feed me the results
- My team complains about issues above (?!?)
- My team only answers my questions – they don’t do any proactive analysis (KM)

A wide range of root causes, and as you read down the list, it’s easy to imagine the range of solutions that could be brought to bear. I have broadly classified solutions for these problems in the list:

KM – Knowledge Management: Some level of documentation, training, knowledge capture, and/or knowledge sharing will be involved
BB – Build or Buy: Includes any technical work, like building a custom solutions, buying and implementing packaged software, and/or configuring the software / information store.

I find it interesting that KM is required in almost all (10 of 13) of the solution cases above, and a “technology solution” (aka I need to Build or Buy something) is required less than half of the time (7 of 13). And how about that little People Management issue that sneaks in near the end …

Questions? Comments? Suggestions? Send mail to webmaster at cazh1 dot com
© Jim MacLennan for cazh1, 2010. | Permalink | One comment |
Post tags:

All articles, blog entries, and other content on this site are licensed under a Creative Commons License

Technical Debt and the Cost/Benefit of Knowledge Retention

Jim MacLennan — Tue, 28 Jul 2009 02:26:00 +0000

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:

developed by Ward Cunningham

Now, before you write off Cunningham as a techie snob or an academic hold-out for unattainable perfection, listen to this healthy dose of reality …

The metaphor also explains why it may be sensible to do the quick and dirty approach. Just as a business incurs some debt to take advantage of a market opportunity, developers may incur technical debt to hit an important deadline. The all too common problem is that development organizations let their debt get out of control and spend most of their future development effort paying crippling interest payments.

I think most of us have seen this phenomenon before; sometimes it manifests as an open willingness to trade quality as just another feature (as measured by the amount of testing before code is put into production). Documentation is another common sacrifice – too often we accept e-mail summaries or PowerPoint outlines as a reasonable facsimile for knowledge capture.

You’ve probably seen this phenomenon where you work, and not just in your IT organization. Many areas of the business will rationalize over-budgeted schedules by summarizing critical findings in a brief email – or, worse, in a Status Update Meeting. “This is an expensive meeting”, I might quip upon entering the room, seeing the conference table ringed with upper-and middle-managers, each weighing in with their understandings and opinions. Don’t misunderstand me – these are typically very effective conversations, with exactly the right people; the folks that know and live the issues, and fully understand the implications of any process change. But my witty entrée was tragically accurate; the understanding and decisions developed at this meeting are too often lost a few minutes after the meeting ends, ideas with a half-life approximately 10 minutes into the start of the next meeting.

Think of it as a knowledge expense (vs. depreciation, as value is lost rather quickly). The expedience and effectiveness of face-to-face communication, with everyone in the same room hearing the same thing consistently and able to ask questions to validate their understanding, typically does not scale beyond the attendees. It’s like listening to a band vs. buying the album (ah, more poetic than downloading …).

In his article, Atwood continues along the Fowler / Cunningham thought process, discussing the need to budget a certain amount of time to pay down our technical debt by going back and finishing that unfinished work; document the things that you sloughed over, rework the inelegant parts of your database schema re code interfaces that rely us a little bit too much on assumptions.

The same can be said for process design and problem solving sessions – remain aware of your level of knowledge debt and budget time to document your findings. I like to call these chunks of captured knowledge “white papers” – I’ll pause while you admire that stunning originality, but there’s a method to my blandness. Calling these things “white papers” helps folks understand the purpose and value of such a document; reasonably short and idea complete. The sweet spot seems to be two to four pages, well-organized, not too wordy, but clear enough that it remains effective months after the design or process rework sessions took place.

Just remember, organizations do the expedient thing all the time, streamlining meetings and decision-making by going light on the documentation. Every once in while, you’ll pay the cost of rework and rediscovery; as our experience grows, and our patience for such “wasted effort” grows thin, task effort times will increase as we invest a little bit more time in better, clearer documentation.

Previously …

Thoughts on Why Tech Folks Hate Documentation (July 8, 2006)
The Iron Triangle – Quality is a Feature that We Choose to Omit from Projects (October 28, 2006)
Innovation That Matters – Substance Over Style (January 12, 2008)
Do you want it good or fast? Prioritizing Time-to-Value over Requirements (February 10, 2008)
Optimizing the Wrong Part of Knowledge Management (March 16, 2008)
Facilitating Innovation: Establishing an Environment of Possibilities (August 22, 2008)
A Plea for Empathetic Communication (November 16, 2008)
Over / Under Communication for Project Managers (June 29, 2009)

Technorati Tags: collaboration, documentation, Knowledge Management,

Questions? Comments? Suggestions? Send mail to webmaster at cazh1 dot com
© Jim MacLennan for cazh1, 2009. | Permalink | No comment |
Post tags:

All articles, blog entries, and other content on this site are licensed under a Creative Commons License

Location, Location, Location: Terminology Confusion in ERP Projects

Jim MacLennan — Sun, 12 Apr 2009 00:12:00 +0000

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 projects I’ve been involved with. Care to add / edit the list?

Generic Terms

A building is what it sounds like – four walls and a roof.
A facility could refer to one or more buildings.
A campus is a generic term for a group of buildings.

Specific Terms – ERP

In SAP, a Plant is a place where materials are produced, or goods and services are provided. A Plant is made up of one or more buildings.
In some Warehouse Management Systems (WMS), a Warehouse refers to a single building. In SAP, a Warehouse is a collection of Storage Areas; a building can contain multiple storage areas, and a warehouse can span multiple buildings.

Specific Terms – WAN

A Site typically designates a point-of-presence to the Wide Area Network (WAN) – a cluster of WAN devices that connects one or more buildings to the network.

Details!

A Chinese proverb states, “Wisdom begins with calling things by their right names.” When bringing companies and cultures together, project managers need to pay special attention to the words; we must be very precise with our language, so everyone understands that we are all talking about the same thing.

Previously …

Excellent series of posts for PMs communicating with non-techs (March 26, 2005)
Bug bad, bug good, bug Bug (May 18, 2005)
Need to watch my terminology (August 16, 2005)
Thoughts on Why Tech Folks Hate Documentation (July 8, 2006)
Communication is the responsibility of … (August 19, 2007)
The Five Fundamental Rules of Project Management (October 15, 2007)

Technorati Tags: best practice, documentation, Knowledge Management, project management, SAP, supply chain

Questions? Comments? Suggestions? Send mail to webmaster at cazh1 dot com
© Jim MacLennan for cazh1, 2009. | Permalink | One comment |
Post tags:

All articles, blog entries, and other content on this site are licensed under a Creative Commons License

KM Overcomplicates: Heisenberg Impact on a VBA Quickie

Jim MacLennan — Sun, 08 Feb 2009 18:08:00 +0000

Got a simple request from one of the folks in Operations; we’re sending out Excel spreadsheets for some quick data gathering, might we do a little basic input validation before they send in garbage that needs to be scrubbed? This person is very sharp, knows a decent bit about what is possible, and this is definitely not something that is worth a major project engagement; “throwaway technology”, a particular fave of mine.

His request was simple – just want to make sure folks enter data into one or two required columns. I’ve done plenty of Excel VBA, and had figured out a simple approach while we were talking (it’s all in the Before_Save() event, naturally), but I couldn’t really tell him how to do it – he’d never programmed VBA before. However, I do have some rather large projects coming this year, and this person’s group will be very important in making timely decisions, implementing change – so I figured that a little lagniappe here would pay big dividends down the road.

Of course, I knew there would be some I couldn’t get all of his requirements right away – I’ve done many similar things in the past, and could anticipate a number of requests down the road. So, a few minutes of Q&A, and I got a decent set of requirements for future flexibility that, if I do a little extra coding now, I could make much simpler in the future.

you may want to jump to the bottom of this post for the lessons learned … gets a bit tedious here …

“Teaching Event” Explodes Scope

Of course, I didn’t want to become the maintainer of another shadow system, so I need to keep this simple. And, I really think there is a lot of potential in quick-and-dirty Excel automation that would do great things for many companies – if more folks knew how to do it. So, I resolved to make the code as modular and self-documenting as I could; I will publish a generic version of the spreadsheet on my code page, so it might be useful Out There as well.

Then again, I have written before about the difficulties of documentation, and I fully appreciate the fact that knowledge capture, while always valuable exercise, adds a lot of overhead – time and complexity, and required concentration. So, I thought I could compound the complexity even more by journaling the programming exercise “real time”, to get some measurements on how much of an impact “good” tech documentation can add. So, I’m composing this blog entry “real time”, to capture a little data.

And, because I just can’t seem to leave complex enough alone, I’ll leave my Twitter client [current fave: TweetDeck] up, and do a little play by play for the Twitterverse as well. Not that I expect much feedback, it’s Saturday evening; had a nice steak dinner with the family, hopefully I’ll stay up through the end of the experiment.

Time Line – Saturday

8:55 pm
He gets a Bright Idea, and starts the blog entry.

9:15 pm
The KM preamble (above) is done, start opening windows. Before I get going, I’ll have four apps open: Excel and the Excel VBA editor, plus a Google Doc (this entry) and Tweetdeck.

I did grab a sample of the spreadsheet to be sent out, with the various columns, header rows already defined, so that’s a nice start.

9:18 pm
Fractal nature of KM – had an idea to #hash tag all the tweets together, so had to go retroactively tag first tweet. Maybe I can code soon …

9:20 pm
Proof of concept / flow was just a message box in the BeforeSave event. Now, I’m off stealing code from old stuff – processing row/column arrays with somewhat predictable locations and dimensions. I need to make what are basically simple loops 99.99% driven with variables, no hard coding. This is the fundamental way to deliver flexibility.

I also will assume future applications that will have multiple tabs with a different data input table in each tab – so will need to build a master loop that runs thru all the tabs.

9:25 pm
Coding finally starts, with a search thru old ssheets. 2-3 more windows opened up. I’m commenting the code while I’m writing it, so the coding time isn’t just raw coding

9:50pm
All stolen code, but built basic structure to process multiple sheets, handle errors at dropout at the end. I think folks might read this source code and get intimidated by VBA – hmmm, might not be helping things. Ah well, on we go …

10:00pm
Some actual new code, still mostly cribbed from other projects – but I’m aggressively genericizing. Also, first comment from twitterverse (@faseidl). Will have to Follow commenters later.

10:05pm
Gonna steal some ReDim syntax, rarely do that, always have to reuse

10:15pm
Been coding for 45 minutes since the last debug, never timed it like this before, kinda interesting

10:33pm
Code is flying, flexible error checking loops all built – writing the magic line of code “If blank then error” now. Probably should structure this bit of code to allow for different types of error checks (<, >, limits, etc.)

10:45pm
Aha, basic loop works, but I made a mistake in my assumption of how to control the thing. I need to specify a column that I will assume is always filled – when I see a blank there, I stop checking. I’ll have to write the “end of check” to be a warning “note: I am stopping here …”

11:00pm
Ok, it’s all done, tested, working just fine. Code was about 140 lines, not a lot. Will do final documentation and code clean up tomorrow morning – kinda tired right now.

Time Line – Sunday

9:45am
Ok, back to it – should be able to finish this up right quick, one would think. Some quick math on the time line above: Roughly 40 minutes (32%) of documentation, 85 minutes (68%) of coding. Not really quantifying how much longer the coding took because I was aggressively cloning (speedup), commenting (slowdown), and genericizing (slowdown).

The sheet works fine, but I do have some work left. Need to package it all up for the original requester, so he knows how to change things; also need to genericize the final thing, so I can publish it / share the knowledge. Again, I’m trying to capture the teaching moment opportunity.

First run throuught the code was to add comments / documentation so folks know how to extend it. The target audience ranges from technically savvy, but no VBA experience, to VBA hackers – I think it’s all in how I structure the code.

9:59am
Getting some additional coding in – trying to take out as many opportunities for typos and such as possible. Restructuring the code so I only have to code the name of the tab to be checked once. I’m actually doing a bunch of coding here, trying to make maintenance as easy as possible – I know these aren’t the most elegant methods, but I am growing conscious of how much time this is all taking. Tradeoffs, always tradeoffs.

10:18am
Code cleanup done – but in testing, noted something I forgot to add. Data checking loop ends with first blank in the “check column”, but if that’s a mistake, and there are data rows below, I should give them a chance to see that – so I’ll let them know what I think has just happened. A bit more detail than just a “success” message – again, this is a data quality check based on my experience with similar spreadsheets.

10:31am
Fine, the actual programming request is done. An email to the requester to deliver, but then I need to finish the Distribution part of KM. Note how I am short cutting the knowledge transfer part of this exercise for the requester – in my email, I told him to let me know when I might drop by, to walk him through the editing / changing process.

Lazy? No, actually quite practical. I’ll be walking him thru the process of making changes to VBA, and I’m not about to document that. Just show him how the basic sheet works, and give him hints on how he can read more , make simple changes if/when interested. I also need to make sure he understands this is not something that IT will “officially support” going forward – just a quick-and-dirty bit of macro coding for a friend.

10:37am
Now, I’m carving out the code, prepping a sample ssheet for sharing … to be posted on my code page. Note that I’m doing some “documenting” by generating sample data, including an error!

10:52am
Here’s is the part of KM that really drives tech folks nuts, methinks. It’s “prep for final distribution”, making everything digestible for a broad, unknown, unanticipated audience. Up until now, the total stands at 75 minutes (39%) documentation, 117 minutes (61%) coding – but from this point on, it’s 100% documentation. Remember, if a tree falls in the forest, no one hears the sound; documentation won’t help until the code is all checked in, text is cleaned up to be made readable, and everything is put where it can be indexed and found.

11:00am
Just starting the editing pass on this blog post – typos, prose formatting When I’m documenting on the fly, I’m not trying to make it look and sound pretty, I’m trying to capture the ideas. However, must invest in the look/feel of final product, else folks won’t read it, understand it, or believe it.

12:00 Noon
I’ll stop the timer on the documentation here – this is a ton of work compared to the size of the original. Just starting the editing pass on this blog post – typos, prose formatting. When I’m documenting on the fly, I’m not trying to make it look and sound pretty, I’m trying to capture the ideas. However, must invest in the look/feel of final product, else folks won’t read it, understand it, or believe it.

Lessons Learned

Twitter definitely adds overhead – can’t quantify it easily, and it was also difficult to keep remembering to post status updates there. Might be because it’s still a new tool, I’m just getting used to it, but it’s a different kind of overhead than the blog entry.
There is a chunk of complexity added because I’m flipping between different windows. Two large monitors helps, but KM requires multi-tasking; if your teams can’t actively, effectively juggle four threads at once, you’ll never get good documentation out of them.
Programming for speed? Hardcode, don’t go for flexibility. The coding time was easily double since I was anticipating reuse, etc.
Only the one comment from the Twitterverse while the project was underway – not sure if that was time of day, target audience, or what. Twitter is still opportunisitc, hit or miss communication – hence the interst (I think) in building up follow lists (ings and ers).
Knowledge capture and sharing can be a relationship management and change management exercise as well. The ability to capture things in writing are important, but not everything
Final time stats, rounded off: Coding 120 minutes (60%), Documentation 80 minutes (40%). I can speed up coding with reuse and practice, but I can also speed up documentation with practice! Don’t give up on documentation because it’s going to shave 40% from all of your effort estimates – unless you honestly track all of the lost time spent looking up definitions, requirements, previous art.

KM is not free, but I think the value is only seen retroactively; folks that have gotten burned with lost requirements, or forced to do rework because the framer’s intent was lost – they seem to be the folks skilled at and committed to KM.

Questions? Comments? Suggestions? Send mail to webmaster at cazh1 dot com
© Jim MacLennan for cazh1, 2009. | Permalink | No comment |
Post tags:

All articles, blog entries, and other content on this site are licensed under a Creative Commons License

Zodiac of Knowledge Capture

Jim MacLennan — Fri, 16 Jan 2009 04:20:00 +0000

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 outout.

However, at the beginning of the year, I start a new folder and a new set of Word files – which means that after week 1, I have the easiest scenario for figuring out how much data entry for the week. And, since last week was typical, I set out to total up my data entry – starting with tthe personal journal files, but including other media:

Format     Words
=====     ======
MS Word   15,300 in 22 documents
Notes      3,000 in 4 documents
Blogs      3,100 in 6 entries in 4 blogs
MS Excel 500 in 5 spreadsheets
Notepad    500 in 4 text files
Mind Maps    300 in 7 maps
Twitter      900
Power Point 700 in 5 presentations
Wiki         500 in 2 wikis, 2 different dialects
          ——
          24,800 words in 1 week

Hmm, that sounds like a lot – accoprding to this guy, I could / should be writing eight books per year …

But then I though of all of the other formats that I was not counting … texting via phone, IM over eight different accounts (thanks, Pidgin!), emails over four different accounts (and four different clients). And what about the code? That wiki item at the end got me thinking; most wiki syntax is faux-HTML, right? But I’ve also had to do work just this week in HTML, CSS, ASP, SharePoint, VBA, dokuwiki, TiddlyWiki …

This whole exercise conjured a series of images in my mind, avatars for a new Zodiac of Knowledge Capture …

Sisyphus: The never ending task of documentation. At times, my “backlog” gets so big, I just file a big chunk away under Future Projects …

Hercules: Prodigious output should be the expectation, not the exception. The world / your work group is ever-hungry for more structured knowledge, and they don’t want to wait thru the backlog – they want stuff now!

Job: Patience is a must – you will write stuff and get no response for months … but every once in a while, a glimmer of hope. Had a conversation this week with someone who noted my Emotional Intelligence post from 14 months back (!). They had seen a class offering at a local college, and we ended up talking about how applicable the skills are to our jobs.

Mandelbrot: You need to be facile when plotting and navigating many levels of abstraction. The reader needs to absorb slowly, peel the onion one layer at a time … but they better be able to drill to the required level of detail!

Pavlov: Repetition – Don’t be surprised when you have to repeat, repeat, repeat, over and over, until you get folks used to the idea of going to the wiki, searching the portal, reading the manual.

Deming: Constant Improvement must be in your mind all the time. There is always a better way to get an idea across (which relates to …)

Xerox: Imitation is the sincerest form of flattery. Let’s not lose sight of the goal – capture and transfer knowledge . So, if you see a more effective method of communicating – learn from it!

Tufte: Clarity in communication is everything. You might think this one should be Strunk, but Tufte drives for clear and effective communication graphically / pictorially, as well as in the written word.

Muse: Don’t rule out creativity; you are competing in the market of attention, and you need to capture the mind before it’s ready to receive. You also can’t always rely on the Same Old Stuff when capturing knowledge; keep experimenting with different tools, take the best, leave the rest.

Cthulhu (CNZ?): Develop skills at multi-tasking, maintaining many threads at once (or multiple arms). Multi-platform, multi-editor, multi-laungauge, multi-markup, etc.

Heisenburg: Be aware that documenting processes can be like measuring them – you will probably introduce some change. This is “stealth process improvement”, and might even be manifest laziness (it’s easier to document a simplified process …)

This zodiac needs a twelfth sign – any ideas?

Previously …

Heisenburg KM (July 13, 2004)
Communicating Complex Technical Concepts (March 21, 2005)
Thoughts on Why Tech Folks Hate Documentation (July 8, 2006)
The Iron Triangle – Quality is a Feature that We Choose to Omit from Projects (October 28, 2006)
Search as the Killer KM App, and Good Writers will Rule the World (November 5, 2006)
Innovation That Matters – Substance Over Style (January 12, 2008)
Facilitating Innovation: Establishing an Environment of Possibilities (August 22, 2008)

Technorati Tags: design, documentation, hands on, innovation, Knowledge Management,
Web 2.0, wiki,

Questions? Comments? Suggestions? Send mail to webmaster at cazh1 dot com
© Jim MacLennan for cazh1, 2009. | Permalink | No comment |
Post tags:

All articles, blog entries, and other content on this site are licensed under a Creative Commons License

The Power of Paper in Business Communications

Jim MacLennan — Thu, 23 Oct 2008 02:14:00 +0000

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 regarding requirements gathering, knowledge capture, resistance to change, etc. All will come out in series, but I’ve got to dedicate a few paragraphs to some foundational topics. These may sound mundane, but I beg your patience – they will establish elements of communication style that act as subtle yet powerful levers in capturing the knowledge, improving the process, and making the changes happen.

The first item on my list has it’s roots in Zig Ziglar and classic sales techniques: the Power of Paper. I found an article on edmunds.com that summarizes it nicely (added emphasis is mine)…

There’s something convincing about hard copies. When something is printed out, it lends substantially more validity to a subject than just the spoken word. Nowhere is this more true than when you’re in the heat of battle. That is, when you’re at the dealership negotiating the price for your new set of wheels.
Rather than just tell the salesman … that Edmunds’ [price] is, for example, $26,393, show them a printout from when you priced out the car. That way, they know you’re not just throwing out numbers. And let’s face it, Edmunds is pretty well recognized so it’s not like they won’t know what you’re referring to.

For some reason, paper bestows a tangible authenticity that has an impact on the conversation. Of course, the Edmunds brand-name certainly bestows additional legitimacy of the printout; it’s not enough to print off an e-mail or start up your word processor and type out a few paragraphs on a blank sheet of paper. Give your paper deliverables some look/feel legitimacy by using all those features that Microsoft / Open Office developers so kindly provided – page headers, footers, multiple fonts, etc. As a concrete example, I have posted my “white paper” document template (available here); it has been refined over the years, and has a number of formatting and content details that present clean, professional looking deliverables suitable for any general topic. I’ve also used this as a base for more complex templates – project proposals, requirements gathering, RFPs, and management presentations.

So what are these “details”? Let me lay out a few Concepts for effective documents, and detail how the template makes it real:

Concept 1: Why take two pages if you can fit into one?
In Practice: Page layout details (such as margins set to a half inch all-around). Paragraph styles that add three or six points before each paragraph or section header (instead of extra carriage returns).

Concept 2: Pages are meant to be printed – the physical page is important.
In Practice: Make the left margin 0.75 inches – we’re adding space for a three-hole punch. Print the page number and total pages on each page – when folks are shuffling the stack, they will know when pages are missing. Print the Last Updated date on each page; this serves as an effective version indicator.

Concept 3: Printed and/or electronic deliverables often contain intellectual property or other information that should be kept confidential
In Practice: Many folks place the corporate logo prominently in the header or footer of every page – this is usually a waste of toner and space (we all know what company we work for – why waste the white space? I prefer the watermark – it’s subtler, yet clearly stands every page – a classy touch (see also Concept 4). Plus, the page footer should say something along the lines of “Proprietary and Confidential”. NB: Every page is key – just putting logos and confidentiality notices on a cover page isn’t enough.

Concept 4: It’s better to look good than to be good.
In Practice: Well, you do need good content – but a polished look definitely adds to the air of legitimacy. This is the biggest reason for the header, footer, and watermark on every page. Also, a Table of Contents is recommended for deliverables that have more than three pages. Note that the template sets the TofC at the top of the first page, but doesn’t necessarily add a page break. Who needs the added whitespace?

Concept 5: Templates can facilitate better content while they support a standard (and polished) look.
In Practice: Good document templates are self-documenting – they feature instructions and best-practice notes within the template itself. Templates for specific types of documents (say, RFPs) will contain a table of contents and a “shell” of empty sections that capture the most effective way to present the information. You can also add stock text for common passages; for example, I’ve written about effective outlines for project proposals. The template for these proposals is actually many pages long, because it’s filled with sample text, such as a list of common project risks or assumptions.

Of course I’m always looking for ways to improve my templates – so any feedback is welcome!

Previously …

Communicating Complex Technical Concepts (March 21, 2005)
Writing like a fiend (August 27, 2005)
Quality requirements for technical documentation are lower than user documentation (April 3, 2006)
Thoughts on Why Tech Folks Hate Documentation (July 8, 2006)
Documentation Redux – a Shorthand Proposal Framework, and the PMO Surprise (July 30, 2006)
Facilitating Innovation: Establishing an Environment of Possibilities (August 22, 2008)

Technorati Tags: best practice, documentation, hands on, Knowledge Management

Questions? Comments? Suggestions? Send mail to webmaster at cazh1 dot com
© Jim MacLennan for cazh1, 2008. | Permalink | One comment |
Post tags:

All articles, blog entries, and other content on this site are licensed under a Creative Commons License

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

Jim MacLennan — Thu, 18 Sep 2008 02:26:00 +0000

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 you can get the techs to agree to create documentation – how do you keep them motivated when they realize that the finished documentation will probably run to over 100 steps on multiple pages?

There’s a really simple trick to make process documentation easy – and we’ll steal it from the Agile Development teams. Time box your process documentation task; for example, you could schedule 1-2 hours before the work starts to develop some documentation (create or add to existing). Then get your work done … and plan on another hour or two afterwards, making updates based on what you just experienced. Don’t spend more than an hour or two – document what you can, then stop and get the work done.

You won’t be finished, of course – but that’s the beauty of electronic documentation and iterative development. The first step of any process should always be “make updates to the existing documentation”. You only have to start with a blank sheet of paper once – the first time. Each time you go through the process, you update the documentation – it will only get better.

A very complex, step-by-step procedure gets a bit more detailed with each iteration
Examples, exceptions, and critical dependencies get called out after you “get bit” – and you never make the same mistake twice
Lessons learned at the end may shift around the order of events – improving quality, speed, and minimizing downstream freak shows

After the first few iterations, you may find your changes, additions, improvements are getting pickier – but that’s okay. I’ve never seen a set of process instructions that couldn’t be improved somehow …

Add checkboxes, page numbers, and space for follow up notes. Make the printed directions a working tool, a piece of paper that helps capture new learnings and process changes for next time.
Add a spot to capture start/stop time or durations. Build up a history of time data – this makes it easier to estimate ETA, scheduling the event, lining up resources, etc.
Rework the process document to function better on your corporate intranet – eliminate the need to print and distribute.
When vendors introduce new versions of software, new features to implement, you’ll be ready to incorporate those changes into your document.

The key is to never think of the document as Finished. Don’t fall into the trap of skipping the Process Review step, before AND after you perform the tasks. Once you stop, it will be hard to get back into the habit; process entropy sets in, and before you know it, you are back where you started – undocumented, out-of-control processes.

Questions? Comments? Suggestions? Send mail to webmaster at cazh1 dot com
© Jim MacLennan for cazh1, 2008. | Permalink | No comment |
Post tags: checklists, Documentation, improving quality, iterations, quality, time

All articles, blog entries, and other content on this site are licensed under a Creative Commons License

Optimizing the Wrong Part of Knowledge Management

Jim MacLennan — Mon, 17 Mar 2008 03:14:00 +0000

I sat in on the report-out session from a kaizen event this week, and something occurred to me as I reviewed a ton of interesting findings in a very short time …

Best Practice

Self-contained deliverables are the most powerful tools for knowledge knowledge transfer you can have in your organization. I’m talking about a document that stands on its own, and effectively communicates an idea without needing the author nearby to explain anything.

The topic doesn’t matter – conceptual white paper, status presentation, process map / instructions, design specifications, etc. The format doesn’t matter – Word (document), PowerPoint (presentation), Excel (spreadsheet), Project (plan), Visio (diagram), and so on. The telling event is when this deliverable is sent out as a pre-read before a scheduled meeting or review. If written well, the time allocated for the meeting is spent discussing questions, clarifications, exceptions, and/or additions – as opposed to explaining the document itself.

Reality Check

Creating self-contained deliverables is hard; it takes skill in a number of different areas to create clear and concise prose, relevant statistics and metrics, relevant and impactful visuals. It’s also time-consuming – well structured examples, screen prints, illustrative diagrams require skills in multiple technologies. Of course, before all the fancy words and beautiful pictures, you have to be able to lay out the opportunity / problem / situation so the reader can quickly get up to speed on the relevant points.

The other challenge, of course, is finding the time to create the content, capture the message, make the connections. It’s always hard to manufacture enough time.

So, what ends up happening? People tend to optimize the knowledge capture process; minimize time spent creating documents by putting together enough material to facilitate the conversation, capture the main points, and help them remember everything that they want to review when in front of the team.

The Problem

Unfortunately, this misses the bigger picture. By reducing the time I spend capturing the knowledge, I’m increasing the time required to pass it along; I am sub-otimizing the knowledge transfer process. If I don’t give my content out for a pre-read, I’ll burn half of the meeting time getting roomful of people up to speed on stuff they could have read the day before.

It doesn’t stop there; the same content would need to be discussed with anyone else who might be interested. And, since we’ve already established that time is scarce for all, these next conversations rarely occur; the opportunity for transferring the knowledge to more people is lost, and as memories dim, the value captured in the original meeting is, for the most part, gone …

… or (more likely) concentrated in the head of the person who originated the whole thing. And people wonder why organizations have trouble retaining knowledge, or why groups develop “super users” that create unfillable voids when they move on.

Catch-22

Unfortunately, when confronted with this situation, most people under time pressure will make the obvious choice – stick with what you know. If you’re facing a deadline, capture the information that you need and deliver the details face-to-face. There’s safety in numbers with this approach; I think 80-90% of the business world takes this route. It gets the job done and no one is really faulted for going this way.

Breaking the Cycle

However, as I’ve noted before, there is a lot of power and possibility when you can leverage your knowledge across many people, without regard to time or place. If you want to do more in your organization, leverage more of your time, and/or get your ideas across quicker than the next person, you need to develop skill in creating self-contained deliverables.

There is no single method or style to create self-contained deliverables. Anyone can do it, but you need to figure out how to adapt and adjust your personal communication style, and change the things that are ineffective. My favorite methods:

Borrow Liberally: Most of the things that I’ve learned about documentation and communication came from other people, other things I’ve seen, read, or heard that particularly worked for me. A writer’s effortless prose, a presenter’s terse yet effective pitch, a diagram’s elegant visualization. Develop the habit of looking for stuff that works, and the curiosity for decomposing it into methods you can use for your own communication.
Study Minto and Tufte … and other practitioners of the art of communication. Minto’s Pyramid Principle is very effective when introducing a reasonably complicated new idea in a short amount of space. Tufte will teach you how to strip out the extraneous information while packing in the pertinent; he’s talking about diagrams and visualizations, but it works for your words, too!
Use the Right Tool for the Job: Every MS Office application has the ability to draw squares, circles, and lines – diagrams in the midst of your spreadsheets, project plans, and documents. But nothing beats Visio for quick diagrams that give precise control of placement, size, and alignment. Similarly, I love Excel’s ability to quickly create beautifully structured tables of information, in a way that gives me fine-grained control over row heights, column widths, font sizes, number alignment, and other effects. Sure – PowerPoint can do a diagram or a table, but it’s much quicker to build it in Visio or Excel and paste into PowerPoint.
Get Feedback: Ask someone whose opinion you trust, and who is at least a decent communicator themselves. Ask them if your written documentation was clear, and did it explain everything they needed to get the whole picture. Better yet, become your own harshest critic; use the voice recorder or videotape your presentations – are you convinced by what you see / hear? Pick up a old document or diagram you created – can you still get meaningful information out of the content or was it really dependent on context?

Take responsibility for the communication – if only to save yourself from the hassle of repeating yourself again and again and again …

Questions? Comments? Suggestions? Send mail to webmaster at cazh1 dot com
© Jim MacLennan for cazh1, 2008. | Permalink | No comment |
Post tags: author, deliverable, Development, Documentation, ERP, Knowledge Management, knowledge transfer, metrics, Minto, MS Excel, MS Office, MS PowerPoint, MS Project, MS Visio, Presentations, style, Tufte, visualization, visuals

All articles, blog entries, and other content on this site are licensed under a Creative Commons License