fighting the lack of good ideas

finally starting to get some good docs amassed

I had a decent library of documentation, templates, hand-offs, slide decks, etc in my pre-Splunk consulting life (technically, I still have them).

It’s nice to be finally getting a decent collection to draw from for my customers in my post-automation consulting life.

document what didn’t work

In a recent episode of Paul’s Security Weekly, an off-hand comment was made about documentation: you shouldn’t merely document what to do, nor even why, but also what you tried that didn’t work (ie, augment the status quo).

The upshot being, to save whomever comes to this note next (especially if it turns out to be yourselfeffort you spent that was in vain.

This is similar to a famous quote attributed to Edison,

I have not failed. I’ve just found 10,000 ways that won’t work.

In light of my recommended, preferred practice and policy of “terse verbosity“, I would strongly suggest not placing the “doesn’t work” in-line, typically. Instead, put footnotes, an appendix, etc. But always

explain everything you did, but use bullet points if possible, rather than prose form

Loads of other goodies in that episode, too – but this one jumped-out as applicable to everyone.

there’s never enough documentation | there’s too much documentation

Documentation is vital. There’s never enough. And there’s always too much. In general, these are the areas I find documentation to fail:

Not Enough Too Much/Many
why-tos (instead of how-tos)

tutorials on things you need

architecture explanation

design philosophy “how we got here”

“why we are here”

future plans / roadmaps

deltas from standards recording

back-/cross-references to extant (even from other vendors / sources) documentation

extraneous verbiage – use terse verbosity

tutorials on things you don’t need / care about

discussion of non-core aspects of the product

how we used to do things

assumption of comprehension

plagiarism – ie, non-attribution of sources

braggadocio (not just excited) tone

different “voices” or styles

I have no quick-fixes. But I hope the above can help to address problems and help those responsible for documenting what they do to make it better. In the tech world, MSDN and developerWorks are the golden standards by which all other documentation should be compared … and to which [almost] all other documentation fails to aspire to.

new documentation should always augment the status quo

In my line of work, I often need to create documentation for clients.

Documentation in general is a Good Thing™.

But good documentation’s goal should always be to augment and improve upon what already exists – not to supplant, downgrade, or muddle what already exists.

A prime example of this has come up with a client partner recently. They asked for “as built” documentation. They failed to define that term. It turns out that their definition of “as built” is a “screenshot-by-screenshot” replacement of the vendor-supplied installation and configuration manuals.

This is a phenomenal waste of time, effort, and space. “As built” should mean to note any deltas or site-specific configurations that vary from or augment the vendor-supplied manuals.

Why is this the case? Because recreating vendor documentation means attempting to do a better job of documenting a product then the people who wrote it! The odds of you being able to do this are extremely low.

In fact, I’d go so far as to say you cannot do it. Ever. The vendor has dozens, scores, hundreds, or even thousands of man-years of experience with the product across the whole team. They know where the source code sits, and can reference it directly. They have the ability to truly say what is and what is not authoritative on the product.

You will never be able to outdo them. Even if you have been using the product since it was in pre-alpha form, you cannot, as one person (or even an outside team of people), possibly have as much experience as the development and documentation teams that design, build, and describe the toolset. They don’t just hold the trump car, they are the trump card when it comes to how something works.

Whenever you document a process, make sure that you document anything that is site-specific about what you did. Make sure you reference the vendor’s materials as often as feasible to make sure you backup your claims and directions with authoritative data.

But don’t worry about recreating what the vendor has already done – your documentation, in this regard, will never be as good as the vendor’s: they publish errata notices, updates, etc. You have to do the same to have a remote chance of matching them.

You will not be successful.

Focus instead on making great documentation that goes hand-in-hand with vendor materials to supplement them; don’t try to supplant them.

organizational knowledge capture, retention, and dissemination

Knowledge capture, retention, and dissemination has been an interest of mine for a long time. I have written about various aspects of it before.

The most vital commodity any organization has is the knowledge of its members – it does not matter if it is a historical society, company, church, or school: the organizational knowledge base is vital to ongoing health of the organization.

I love the picture of the “Tree of Wisdom“: at the ground there is a meadow of data, from this data information roots are gathered, the roots grow into knowledge branches, and at the end is the application of that knowledge in wisdom leaves.

Data is easy to come by.

Information similarly so.

Knowledge, taking information and transforming it into a more-usable form, is important.

When to apply that knowledge – aka using wisdom – is the topic for another post.

Capturing Knowledge

There are a host of available tools for capturing knowledge – text files, brown bags, PowerPoint, SharePoint, blogs, Plone, wikis, etc. The “best” one to use is the one you use.


Getting team members to contribute to organizational knowledge pools can be difficult – unless it is an organizational priority .. a part of the organization’s culture.

Incorporating this culture switch (if it’s not already innate to the organization) needs to be done not merely as a top-down directive, but encouraged via bottom-up interest.

Retaining (Managing) Knowledge

Now that you’ve captured (or started capturing) the organization’s data, managing it becomes the next task of import.

For example, should the KB article written 5 years ago be updated, replaced, or left alone?

Who is responsible for managing all of the information that has been collected? Will it be self-managed and -directed, will there be a curation team, will it be a combination?

Who determines the process for taking “internal” knowledge and “promoting” it to “outside” knowledge?

How are these roles going to be managed as the team changes memberships through people leaving, entering, and shifting in the organization?

For extremely small organizations, formal curation may be unnecessary. Perhaps since everyone knows everyone else, or the knowledge domain is so small, everyone’s individual contributions will remain fairly static and the “promotion” path will merely be proofreading (eg a historical society’s archives – the archives may be extensive, but the material doesn’t ‘change’ all that much (excepting being added-to, of course)).

For very big organizations (like the MSDN documentation available on, many layers of curation are likely going to be needed – proofreading, formatting, verifying, etc.

Finding the right balance of self-direction and organizational management can be tricky.

Disseminating Knowledge – Getting The Word Out

All of the captured knowledge in the world is useless if you can’t find it – and knowing where to look is vital. A close second to knowing where to look is how to find it.

Where is it?

There needs to be a solid document, landing page, directory, table of contents, etc so that new members (or folks who forget) can find the tribal knowledge that exists in the organization.

As a part of the new-hire\introduction\etc process\period, be sure to tell new members where information can be found, and who to talk to about certain major topics.

Finding it once you know where to look

“Search is a hard problem.” Google’s own Udi Manber said that. Anna Paterson at Stanford wrote, “Writing Your Own Search Engine Is Hard.”

Search in general may be hard, but many tools handle at least basic (and some fuzzy) searching well – OSQA, WordPress, Plone, Drupal, and many others. If, in addition to categorization, a tag taxonomy is employed, quickly finding content relevant to the searcher’s wants\needs can become easier.

“A tag is a keyword or label that categorizes your question with other, similar questions. Using the right tags makes it easier for others to find and answer your question.” {SO description}

Knowledge contributors should be the primary agents of tagging. However, consumers should be able to suggest additional tags. Administrators\curators should be able (under unusual, but well-defined, circumstances) to remove tags.

The human factor

For any given topic / knowledge region in the organization’s realm, there need to be established “experts” and “mentors” who will help guide new individuals through the fog to locate the buoys to be able to navigate themselves into a clearer understanding of the new world they have been made a part of.

Apprenticing upcoming experts into the organization is the single most vital aspect of the knowledge capture process – if it is not disseminated, it doesn’t matter if it is captured.