J.D. Meier's Blog

Software Engineering, Project Management, and Effectiveness

The Power of Learning Docs

The Power of Learning Docs

Rate This
  • Comments 2

The key to effective knowledge management is to throw away documents.   You can’t get attached to what you write down.  Otherwise, you can’t learn and it won’t evolve.   But there is a trick …

You throw away the document, not the learning.

I learned this the hard way.   Several years back, I was trying to rewrite a document that had a bunch of gems, mired among bad ideas and bad writing.   It was the equivalent of spaghetti code.   It was hard to figure out what was the insight, what was the action, and what was just interesting information, but not critical path.

It Often Takes Longer to Reshape than to Start Over

I spent close to 40 hours trying to rewrite it.   Granted it was a long document, but at some point I had to ask myself, which was faster – re-writing it, or starting over?   Eventually, I realized, the right answer was to start over.

So I started with a blank document.   And then I carried over the gems, and elaborated from there.  Within 8 hours, I was done with the finished document.

The big lesson I learned was how difficult it actually is to reshape something that’s off, especially when it comes to written information.   Since this was prescriptive guidance, it had to be relevant, actionable, and timely.   It had to be insanely useful.   And to do that requires a lot of manipulating words and phrases until the bright ideas compile into actionable guidance with conceptual integrity.

Throwing Away Documents is Hard if You are Attached

But “throwing away” a document was tough.

At least, it was tough until I realized that all the document really was, was a learning doc.   It was a place to experiment and put ideas down on paper and bounce them off of other people, and get the collective perspective.   The problem was, this learning doc, wasn’t the same as a bunch of notes.  It was meant to be the final document.  It was on path to be so.  

But, along the way, what I failed to realize is that it baked in a bunch of our learnings.

It didn’t yet reflect creative synthesis, or distillation.

It was more like a trail up the mountain, and we were still on our way up.

Throw Away Documents, But Carry Forward Lessons Learned

I had a conversation with John Socha, the guy behind Norton Commander.  I explained the challenge of producing useful documents, and how our learnings get in the way, if we don’t let the documents go.   Surprisingly, he said to me, “Exactly!”

He continued and basically said that it’s the mistake a lot of people make.  They hold on to their documents long past their usefulness, and don’t let the documents go, but carry the learnings forward.

I don’t know what painful lessons John had gone through to learn that, but at the time, it was fresh on my mind, and it had cost me 40+ hours of trial and error to move a document forward to learn that vital lesson.

Fresh Docs Help You Express Ideas More Clearly

You need to be able to throw documents away to create something better in its place. 

When it’s pen and paper, it’s easier to throw something in the trash bin.   But, when it’s a digital document it’s, it’s easy to forget what it feels like to start fresh.   You don’t lose something.   You gain something.  It’s whitespace, where you are free and able to express things more clearly, now that you have more clarity.

Whitespace loves creative synthesis and distilled ideas.

It’s a breeding ground for new ways of expressing what you now know that you have climbed further up the mountain.   If the path before you is riddled with your previous learnings, it can tough to see how to pave your way ahead, or worse, how to make a cleaner path for others to follow, which, after all, is the point of the knowledge and information you are attempting to share.

Learning Docs Are Your Friend

They are you friend.   If you let them go.

They come in all shapes and sizes.   They may even resemble raw notes.   What’s important is that you acknowledge that they are just that.   They are learning docs and you need to be free to throw them away and start from scratch at any point in time.

This is fundamental to creating a relevant, actionable, and timely document set that helps your users climb the mountain.

This is especially important when it comes to collaborating on documents.   In fact, that’s exactly where I first learned this lesson, and spent 40 hours trying to fix an 8 hour document.

Versions + Boneyards Help You Throw Away More Effectively

Once I learned that lesson, I had to find ways to incrementally and iteratively evolve documents as a team (or by myself.)   I adopted some simple conventions.   One convention that served me well is to version documents in the title:  MyDocument – v1, MyDocument – v2, MyDocument – v3, etc.

It takes judgment when to decide it’s worth calling the document a new version, but it also helps to let things go from one version to the next.

Another practice that has worked well for learning docs is to have a Boneyard section at the end of the document.   Literally, a dumping ground at the bottom of the document with a big heading called Boneyard.   And that is where information can go to rest, and be resurrected as needed.   This helps make it easier to let information go, since it’s never far from reach, while you work on the critical path up front.

It Takes Longer to Rewrite Than Start from Scratch

It often takes longer to rewrite a document, than start form scratch simply because you are mired among various stages of rot and decay, while other parts are more fresh and vibrant.   While you can hack away at the decay, tuning and pruning is often not as fast as simply lifting the healthy parts forward.

I think the concept of learning docs is an important one.  

And, not necessarily an obvious one.  You may never have the benefit of a painful experience of trying to rewrite something that takes longer to rewrite than to start from scratch.   So you may not even notice just how much the lack of a learning docs approach is holding you, or your team back.

This is especially true if you work on a team that is used to sharing documents and pairing up on them.   Chances are, they iterate on the same document, with version control, until the document is done.   And, the document, along the way, is heavily laden with comments, and undistilled insights, stepping stones, and spaghetti.   And, it’s a heavy process to bring the document to closure because it’s a continuous navigation through the jungle of half-baked learnings.

Make It Easy to Throw Away Docs While You Embrace the Learning

The heart of the problem is that the document at any point in time reflects both creative synthesis and distilled ideas … and learnings in progress.  Meanwhile, people are injecting their latest thinking, which may or may not actually be distilled points or creative synthesis.   This is where the concept of learning docs shines:

Acknowledge that the documents are learning docs in progress, and make it easy to throw them away while carrying the good forward.

Getting attached is how you hold yourself back and how you limit the pace at which you can share the best thinking in a non-cluttered, clear, and concise way.

Hopefully, the power of learning docs will save you a lot of pain and wasted time and energy.  It’s one of those insights that I wish somebody would have shared with me long ago, before I finally stumbled on it myself.   Then again, it might be the type of lesson that you only fully appreciate once you have the problem at a grand scale.

  • Something that has really helped me is to write ideas on A6 cards, place the cards in a box, and review them regularly. I also have a revision system for texts longer than one paragraph that is basically a 43 folders system (that one is for papers of up to A4 or folded A3).

    In both systems, it's easy to review, restate or discard old things, and add new ones.

    Esp. the one for A6 cards helped me to get comfortable with reviewing, restating, discarding and adding things.

    Previously, I used to write down everything in notebooks or lengthy files, but was very unsatisfied with it, because that format was too rigid for my purposes.

  • @ Sophia -- Cards is a great approach.

    You reminded me that many of our best team sessions involved sprawling many pages of chapters all around the room.   We would then walk the room and do eyeball for flow, and cross-check headings to make sure the right ideas popped.   And, then we would drill into various nuggets and come at them from different angles.

    Cards would have helped us more as an intermediate step to our chapters on the wall approach.

Page 1 of 1 (2 items)