WHY Should I Document My Challenge?

I’ve written another post, ‘HOW Can I Document My Challenge?’ to go alongside this one - the two posts will serve as the basis of my Documentation Workshop at the Berlin event, so I encourage anyone else interested in documentation to add to these posts and use them to communicate the importance of documentation to others!

Documentation means communicating your experience and discoveries - ensuring that others don’t make the same mistakes, and making the work we do stronger, as it can build upon the ideas and experience of many people rather than just ourselves.

Documentation is about turning an individual or group experience into our knowledge commons - something that can benefit anyone, anywhere, at any time.

OK, here’s an easy multiple choice question for you:

Who benefits from a well-documented project?

a) you

b) other people

c) the project itself

d) All of the above

Yep, the answer is d) All of the above.

How does it help YOU?

By documenting your project well, you have the immediate benefit of clarifying and focusing your thoughts - in order to communicate a messy discussion or a trial & error process to others, you have to filter & summarise. This process usually brings up other questions, other solutions, or aspects which you hadn’t even considered beforehand.

There’s also a huge benefit to Future You.
Now, you haven’t met Future You yet, but I think you would get on well with them, you have a lot in common. Future You is likely to be interested in the topic you’re working on now, and at some stage - perhaps in two weeks, in two years, or in twenty years - Future You will want to know what happened at that workshop during OSCEdays '16. Future You does not have such a good memory as you think! Future You will need a refresher on what happened, access to the files that you used, links to relevant online resources, and a ‘how-to’ guide to reproduce or build upon the original process and results. By creating comprehensive documentation of your project, you are making Future You’s life much easier. Future You will be eternally grateful.

Be kind to Future You! (Wikimedia Commons)

Documentation also helps you because it is the first step to building collaboration, to finding new ideas, to communicating your needs and encouraging contributions.
You can never know exactly who might be interested in working with you to solve your problems, but only through documentation and communication can you let them know you’re working on a problem in the first place.
Which brings us to…

How does it help OTHER PEOPLE?

Clear, easy-to-understand documentation allows somebody else to quickly understand what the challenge is that you’re working on, what you have tried so far, how far you have come, and what problems or interesting questiions you have identified.

With this information, people looking through your documentation are able to very quickly understand if this topic is of interest to them, and if they can help in any way, whether that be by directly solving problems or contributing ideas, or else by spreading the word and putting you in touch with relevant people.

Good documentation saves the reader (your potential collaborator) time.

Maybe the experience that you have been through can help others to see the challenge from another perspective, maybe it will be directly relevant and useful to their work, or maybe they will see a connection between you/your project and other people in their network.

Without this information being presented in a useful, accessible and detailed way, they can’t even begin to understand what you’re working on, let alone help you or take the idea further.

How does it help THE PROJECT ITSELF?

You’re a human being (I assume… hello to any bots and sentient dolphins reading this as well!).

Human beings get distracted, their interests change, their circumstances change. Just because you’re interested enough in your topic to be involved in an OSCEdays challenge, doesn’t mean that you are committed and responsible for carrying this project with you over the course of your life. And you shouldn’t be!
Your project, and the ideas and discoveries around it are actually more resilient if it doesn’t depend on a single person.

Documentation is the first step towards freeing yourself of the heavy burden of sole personal responsibility, and allowing others to share the task of stewarding the project. It’s also an act of invitation and inclusivity. By putting your thoughts and experiences out there you’re inviting dialogue and improvement. You’re showing people that you invite and value contributions. And it means that if you get hit by a bus or attacked by a rogue sentient dolphin, your project and ideas will live on.

you can never be too careful… (CC-BY Ross Hawkes)

One more thing - you can’t possibly know who may or may not be able to help develop your project, or whom your project might be able to help. If you keep the information to yourself, only sharing what you deem relevant with people you deem relevant, you’re missing out on potentially useful connections. By making the information public, under an open license, anybody is able to use the information or pass it on to become useful to others.

For any good idea - particularly one related to the sustainability of our planet - its resilience and diffusion depend upon the contributions and stewardship of many different people - being overprotective of the idea, or choosing not to share it until it’s ‘ready’ can jeapordize its survival!


Sharing is a two-way street, so please document your events and post them as described by Sam.