Introducing Super-BOSCARD: my new in-depth technique for writing an essential Terms of Reference.

WARNING: Don’t read this article if you’re just trying to pass an exam. I’m giving you the real-world view, from twenty years experience as an IT professional, rather than what a textbook will tell you.

Table of Contents

When you’re doing a piece of work, do you ever feel like you’re floundering around without a clear sense of direction or purpose? That you’re not sure what you’re supposed to be doing, or why you’re doing it? That your boss hasn’t told you what’s going on? That the various people you’re working with don’t agree on what’s supposed to happen?

If so, the way to fix it is simple: you need a good Terms of Reference.

PART 1: Terms of Reference

What is a Terms of Reference? 

It simply tells you, for a piece of work, what you’re trying to do, and why you’re trying to do it. It can form an agreement between the stakeholders as to the Who, What, Why, When, and How of the work.

Over time, people can “forget” or change their mind over what they were asking for. The Terms of Reference lets you go back and see what you originally agreed, and then update it where necessary.

If you ever find yourself thinking, “What the heck am I trying to do here?”, then you need to take a step back and create a Terms of Reference.

Why use a Terms of Reference?

The TOR can give you a clear understanding of the work. Clarity is essential, to avoid wasted effort and wasted time. It lets you find out what is really needed and required. It also lets you communicate the work with the other people involved, and lets you know when you have finished.

Without a good TOR you’ll often be going around in circles, never really knowing where you’re supposed to be going.

Who should write the Terms of Reference?

It doesn’t matter too much who actually writes the Terms of Reference. It’s more important that it gets agreement between the senior stakeholders who will be involved in your project, to make sure everyone is happy with the final understanding. 

A Terms of Reference can be written by a Project Manager, a Business Analyst, a Product Owner, or anyone with a vested interest in the work being set.

In theory, a Project Manager or some kind of Product Owner or senior stakeholder should write the Terms of Reference. In practice, I’ve found that it’s often the Business Analyst that will write the Terms of Reference, and then present it for discussion and approval. 

The Terms of Reference can be quite detailed, so to be written well it needs a person who can see both the big picture and the detail.

If your manager gives you a piece of work that you don’t fully understand, you can create your own Terms of Reference—it can be small and concise—to help you clarify the work before you start.

How big does a piece of work need to be before you need a Terms of Reference?

Anything that’s going to take a day or more, or that isn’t completely clear, could often benefit from a good Terms of Reference. It’s much easier to do the work when you’re clear on exactly what the work should be!  

If the work is quite small, your Terms of Reference could just be a few key bullet points. If the work is a much larger project, you might end up with two or three pages to cover a full Terms of Reference.

How important is a Terms of Reference?

A good Terms of Reference is absolutely VITAL! Without it, you won’t agree on the work you’re doing, and you’ll probably end up wasting a lot of time, and producing work that doesn’t meet requirements, because you don’t know what the requirements actually are!

Without a Terms of Reference, you literally don’t know what you’re doing! There will be the huge tendency to jump towards a solution before you really understand what you’re solving.

Isn’t this planning in advance? I’m terrified of being accused of “doing waterfall”!

Don’t think of it as planning in advance, consider it thinking in advance. I’m arguing this is NOT waterfall. Agile is useful when things are changing, but not everything changes all the time! 

You need to distinguish between fundamental, earth-shattering change, and smaller changes you can live with. An airline will still be flying planes in five years time; an online clothing retailer will still be selling clothes in five years time. Often, change comes as a big step change, then only very small incremental and continuous improvements. 

The much bigger peril is that you “fail to plan, plan to fail!” Without a decent understanding of what you’re trying to do, your agile techniques won’t work, because you have nothing to aim for. You and your team will just end up confused, and you’ll waste a lot of time.

So step away from the JIRA, and set your epics and stories aside for a moment, and consider the big picture.

Summary: What is a Terms of Reference?

  • Lets you clarify and understand a piece of work before you start it.
  • Reveals areas where you are not yet clear, where you need to ask questions.
  • Tells you what the work needs to achieve to be successful.
  • Gives everyone on the team a clear understanding of your goals.
  • Lets you communicate and agree the shape of the work with senior people.

PART 2: The standard BOSCARD technique

One of the classic tools to create a Terms of Reference is called BOSCARD. It usually stands for Background, Objectives, Scope, Constraints, Assumptions, Risks, Deliverables.

It’s really just an acronym to get you thinking through the most important things you need to consider. 

There’s also a similar, shorter form called OSCAR, which removes the Background and Deliverables, although I don’t recommend that you do this, because I’ve found in practice that both of those sections are important.

Where is most of the value in BOSCARD?

Most of the time, especially for smaller pieces of work, I’ve found that most of the value comes from the BOS-D, rather than the CAR. In other words, Background, Objectives, Scope, and Deliverables gives you most of the power of BOSCARD. The CAR section—Constraints, Assumptions, Risks—is more useful on larger projects.

It’s best to tackle the BOS before the CARD, because the information in the CARD section largely comes out of what you discover when producing the BOS.

PART 3: Introducing Super-BOSCARD

What’s better than BOSCARD?

Although BOSCARD is a useful starting point, I’ve found that in practice it misses out a lot of key information that you often need to know. BOSCARD itself only does half a job. In this article I’ll show you a fuller and richer tool 

Introducing Super-BOSCARD

To overcome some of the real-world problems I was having with BOSCARD, leaving me with an incomplete Terms of Reference, I decided to beef it up! So I created Super-BOSCARD. It’s still basically BOSCARD, but with a few more things that it’s useful to consider.

Of course, with great power comes great responsibility. Don’t feel that you need to include every heading within your Terms of Reference. There’s nothing worse than reading a document that just repeats the same irrelevant things over and over again because it’s been written to conform to a template.

So use your judgement. Super-BOSCARD is only there to help you produce a Terms of Reference. The Gods of Computer Science won’t come down on you like a ton of bricks if you leave some things out if they’re not relevant!

So pick and choose, to create something that’s right for you. Don’t create something too long and unwieldy. Feel free to combine categories, or ignore categories—whatever gets you the best end result.

As a general rule, the larger the piece of work, and the longer it will take, the more of these headings you should use, and the longer and more detailed your Terms of Reference should be.

See these headings as a starting point for discussion. Often, the discussion that you generate will be as useful as the conclusions that you eventually reach.

PART 4: The elements of Super-BOSCARD – Just read this if you’re in a hurry!

Super-BOSCARD is made up of four parts: three sets of things to consider, and a set of filters to use afterwards to validate that your Terms of Reference is suitable.

The four parts of Super-BOSCARD are:

  1. The current world: where are we now?
  2. The perfect world: where would we like to be?
  3. The imperfect world: what might hold us back?
  4. Filters: is our Terms of Reference likely to be correct?

I’ve presented these items in the approximate order you will usually consider them.

The current world

This is a part that many people miss, but it’s important to set the scene, to understand how the work came to be requested. People will try to rush you here, and not define the problem accurately—you must resist this! They all want to skip straight to solutions, but this is a huge mistake.

BackgroundWhat brought you to where you are now?
ProblemWhat specific problems do you need to solve, and who is experiencing these problems?

The perfect world

This is the exciting part, for what we’re going to do!

VisionWhat’s the opportunity? What’s the big picture of the future state the work is trying to achieve. As Einstein said, “If you can’t explain it simply, you don’t understand it well enough.”
ObjectivesHow do you know you’ve met the vision? You could use SMART goals, OKR (currently fashionable), or just write some simple clear statements of what you need to achieve.
BenefitsWhat are the business benefits of the work? Increasing revenue? Cutting costs? Saving time? Can we quantify these benefits with figures? (Sometimes you can capture the benefits within the Objectives, if you are using a technique like OKR.)
ScopeWhat will you do, and what will you not do?
Enterprise ContextHow does your work fit into the wider goals of the whole organisation?
ReasonsWhy are you doing this work?
DeliverablesWhat will this work actually produce?
Roles and ResponsibilitiesWho is involved, and what will they do?
GovernanceWho will approve and sign-off on the work? How will it be governed?
ApproachHow will you tackle the work, as your high-level approach? Not essential, but it’s good to get general agreement before you start, especially if there are some quite different routes you could take. Make sure you don’t get bogged down in detail if you choose to discuss the approach.

The imperfect world

This is the boring part, with all the difficulties we might face.

ConstraintsWhat existing problems do we have to live with?
AssumptionsWhat do we assume is true, which we will validate and question later?
RisksWhat could go wrong, and how could we deal with it?
DependenciesWhich other people, systems, departments, projects, and organisations, are we relying on?
FinancialWhat’s the budget, and do we have enough money?
TimescalesHow long do we have? Are there dates we need to hit for legal or regulatory reasons? Can we break this down into milestones?
Legal and RegulatoryAre there any legal or regulatory hurdles to clear, or things that would stand in our way?
EthicsIs our work fully above board? Are we causing any harm?

Filters and Checks

This makes sure you’re on the right trajectory. These aren’t usually headings to write down; they’re checks you can do on your work when you’ve got a good first draft. It’s a validation of your Terms of Reference.

ConsistencyDoes anything in this Terms of Reference contradict itself?
AlignmentDoes your work match to the strategy of the company, your department, and your manager?
SimplicityAre you using a sledgehammer to crack a walnut? Are you making things harder than they need to be? Could you get the same results with less work?
Sanity CheckIf you showed your Terms of Reference to an intelligent friend, would it make sense? Or have you gone crazy?
AgreementDoes everyone who needs to agree with what you’re doing actually agree? Do you need formal sign-off or approval?

PART 5: Running a meeting, interview, call, or workshop to build a Terms of Reference using Super-BOSCARD

You need to make sure that the senior people with an interest in your work are able to give you their views on what you need to do. They will help you to build a holistic Terms of Reference that sees things from all the appropriate angles.

Sometimes this is easy, and other times it’s a bit like getting blood from a stone! Quite often you find that people only have a vague notion of the work, and when you try to actually pin them down on details they become very waffly and evasive, and lack any real clarity. That’s actually a good sign, because it tells you that something is wrong, and it really makes the case for why you need the Terms of Reference.

Set a formal agenda before the meeting

I recommend setting a formal agenda for your meeting or call, and publishing it in advance (put it in the meeting invitation). Some people might then start to prepare some more structured thoughts in advance, if they know they’re going to be grilled!

I usually start with a 1 hour meeting. These days, if you go for anything longer than an hour it’s very difficult to actually schedule a time when everyone can attend. Also, people will switch off after an hour or so, and lose concentration. Once the hour is up, you can go away and start to write up what you’ve got so far, make sense of it, and the gaps and further questions will become more obvious. You can then have another meeting to clarify those areas.

Meeting agenda for a Terms of Reference meeting

You can remove any agenda items that you don’t think are relevant for your particular piece of work. Copy and paste this into your meeting invitation:

The purpose of this meeting is to understand exactly what this piece of work involves, and exactly why we are doing it.

Here is the agenda for our 1 hour meeting. Time is quite tight, so please be on time!

  • Welcome and Introduction (5 minutes)
  • The Current World (10 minutes)
    • Background to where we are now
    • Problems we need to solve – we need to understand this thoroughly
  • The Perfect World – where we want to get to (25 minutes)
    • Vision
    • Objectives
    • Scope: in scope and out of scope
    • Enterprise context for where this work sits in the wider company
    • Reasons for doing this work
    • Deliverables
    • Roles and Responsibilities
    • Approach (if time): the high level way we will tackle the work
  • The Imperfect World – things that could hold us back (15 minutes)
    • Constraints
    • Assumptions
    • Risks
    • Dependencies on other people, systems, departments, projects, and organisations
    • Financials and budgets
    • Timescales
    • Legal and regulatory
    • Any ethical concerns?
  • Wrap up, actions, and next steps (5 minutes)

PART 6: Questions to ask during a Terms of Reference meeting

Here are some questions that you can ask, for each heading, to get the discussion started.

You don’t need to ask all of these questions, but they will give you a good starting point. Pick and choose the most appropriate questions for your situation. Don’t ask every single question, or you’ll be there for hours!


  • Tell me why you decided to start this piece of work?
  • Where did the idea for this work come from?


  • What sort of problems have you found that led you to kick off this piece of work?
  • Who is experiencing these problems?
  • Can you put on a figure on how much time or cost these problems are causing us?
  • How much more revenue could we make if we could fix these problems?
  • Who is asking you to fix these problems?
  • Has anyone tried to solve these problems before? How did it go?


  • What the vision for how things will look when this work is completed?
  • What’s the big picture for how you want this work to turn out?
  • What do you want to have achieved when we’re done with this work?
  • If you could wave a magic wand, what would thinks be like when we’re done?
  • Where would you like this work to be in 12 months time?


  • Can we make a bullet-point list of the high-level objectives for this work?
  • What are the 3-5 main big things you’d like this work to accomplish?
  • Which of these objectives are the most important?
  • Can we prioritise these objectives?


  • What are the benefits of doing this work?
  • Are we aiming to make more money, or cut costs, or save time?
  • Can we assign benefits to each of the objectives we identified?
  • Can we put numbers on any of these benefits?


  • Which parts of the business do you think will be affected by this work?
  • Which areas do you think we’ll need to look at?
  • Which systems do you think this work will affect?
  • Are there any specific areas we should take out of scope and not look at?
  • Is there anything we can take out of scope for now, to reduce the amount of work we need to do?

Enterprise Context

  • Where does this work fit into the bigger picture for the company as a whole?
  • Which strategies are we aligning with when we do this work?
  • Is there anyone else here working on something similar?


  • Why is it important that we reach these objectives?
  • What are the big reasons that you want to do this work?
  • Can we list a reason for each of the objectives we identified?


  • What would you like this work to actually deliver?
  • What format should the deliverables take, e.g. Word documents, software?
  • Who will use the deliverables, and what will they do with them?

Roles and Responsibilities

  • Who will we be working with on this?
  • Who are the senior people involved?
  • Who will we be working with day-to-day?
  • Who is the overall decision maker?
  • Are there any specific stakeholders we need to identify now?
  • Who will accept the deliverables when we’re finished?


  • Who needs to approve or sign off on things, and what will they want to see from us?
  • How will we govern the work to keep it on track?
  • Do we need a Steering Committee or Project Board?
  • Do we need regular status updates?


  • What general approach do you think we should take with this work?
  • How do you think we should start? 
  • What are the first steps we need to take?
  • How do you think we should break this work down?
  • Where do you think we should start with this work?
  • What do you think will be the main workstreams involved?
  • What project management methodology do you want to use?


  • Are there any problems you can see we’re going to face?
  • Is there anything that’s going to stand in our way?
  • Are there any constraints or things we’re going to have to work around.


  • What are we assuming here when we do this piece of work?
  • Is there anything we’re assuming in our definition of the problems that might not be true, or that we need to check and validate?


  • How risky do you think this piece of work is?
  • What risks are we facing here?
  • What could go wrong with this work?
  • Is there anything that could happen that would send us off-track?
  • Have you thought about how we could handle these risks?


  • Who else are we depending on to get this work done?
  • Are we going to need time from any other team or department to be able to do this work?
  • Do we have any people, systems, departments, projects, and organisations, that we’re depending on to be able to do this work?


  • What’s the budget for this work?
  • When does the budget start and end?
  • Does anyone need to sign off on the financials?


  • When does the work need to be completed by?
  • Do we have any hard deadlines that we absolutely have to meet?
  • Can we break the work down into phased deliveries?

Legal and Regulatory

  • Are there any laws or regulations that we’ll specifically need to be aware of?
  • Who can we check the legal position with?
  • Who will sign off on the legal and regulatory side of things?
  • Does this work comply with the company’s internal policies?


  • Are there any ethical concerns about this work?
  • Would we be causing anyone any harm by this work?
  • Does this work inadvertently discriminate against anyone?
  • Would we be comfortable if this work became public knowledge?

PART 7: Presenting your Terms of Reference

It’s perfectly acceptable, and often desirable, to create a Terms of Reference for pieces of work you’re doing on your own.

However, once you’ve done your analysis you’ll often need to present it to other people, to communicate what you’re doing and to seek senior approval.

The options for your presentation are usually:

Directly in an emailGood if the Terms of Reference is short, and the piece of work is quite small.
PowerPoint slidesA good middle ground when you don’t want to be too formal. People seem to like PowerPoint because they think it gives them an excuse to be vague and woolly, and not have to think too hard!
But you’re going to lull them into a false sense of security, then whammy them with the good stuff!
Careful you don’t get bogged down in making it look pretty, rather than spending your time on the actual analysis.
Word documentMany people seem to think that a Word doc is too formal, or they might actually have to think and concentrate! But if you’re doing a larger piece of work, a Word document is usually easier to annotate, add reviewer comments, and print out for easy reference.
Wiki pageGood when you need to share your Terms of Reference with other people, and it might need to change. The wiki is useful for keeping a history of changes, and who made them.
Options for presenting a Terms of Reference.

Conclusion on using Super-BOSCARD to write your Terms of Reference

Having a great Terms of Reference is vital if you want to do great work. It builds agreement and clarity on the big picture for what you’re trying to achieve.

Using Super-BOSCARD makes it easy to build a comprehensive and bullet-proof Terms of Reference.

Give it a try on your next project, and let me know in the comments below how it works for you!

References you might find useful:

BOSCARD article at Project Smart.

BOSCARD article at BA Guru.

Wikipedia article on Terms of Reference.

O’Reilly publishing: introduction to OKRs (37 page free PDF)

How to use Readability Scores


Readability score resultsIf you need to make sure your writing is clear, the website Readability Score can help.

I’m not connected or affiliated to this website or its creator in any way, I just find it very useful, and wanted to share it with you.

Much of my working life involves writing, so to all intents and purposes I am a professional writer.

I want to show you why I find this site useful, and give you some recommendations on how to use it.

What is a readability score? What is a readability index?

The concept of a readability score (also known as a readability index) goes back many years, really hitting its stride in 1975, when Rudolf Flesch and J. Peter Kincaid built their Flesch–Kincaid readability tests for the US Navy.

The idea is that by looking at your writing, and making some calculations, we can figure out roughly how easy it is for somebody to understand what you’ve written.

It’s an automated calculation, so of course it’s not perfect, but it’s a very useful guide. The most common measures that these scores look at is sentence length, word length, number of syllables in your words, and the number of characters (letters) that you use.

Sometimes it’s difficult for a computer to count syllables accurately, so the measures are sometimes not 100% precise, but from a practical point of view that doesn’t matter.

There are two basic types of measures. The first is just a score, which doesn’t mean much by itself, but can be used to compare one piece of writing to another.

The second measure, which Flesch and Kincaid developed, and several others have followed, is more useful to us. It shows the average American school reading grade needed to understand your writing.

What are the most popular readability scores?

There are several readability tests that ultimately boil down to a US reading grade. This means that we can run several tests, compare them, and take the average.

Here are the big guns of the readability index world. They all work in different ways, and the links below take you to Wikipedia articles so you can find out more. They produce results of a US reading grade that are usually no more than two or three grades apart.

(Readability Score gives you these links when you see your results, which is nice.)

How does work?

This website was built and maintained by Dave Child, who’s based in the UK. I don’t know him personally, but he’s very friendly and responsive to email, if you have feature requests, etc.

The site is nice and easy to use, and looks good. You can either paste some text directly into the site (which is what I do), or upload files, or point the site to a URL web link that contains your text. The site can even monitor your links, such as your homepage, and alert you when certain readability thresholds are breached.

The results are very clear and easy to see, and I’m sure you’ll find it very useful.

You get to see the various reading grade levels for your writing, and an average.

You also get keyword density, ie how often certain words or two-word phrases appear. Personally I don’t need this, but if you write with SEO in mind it can be helpful.

Word count, sentence count, and average words per sentence are useful. I’ll give you some recommendations below for how you could use this.

The longest sentence is a crucial metric, and one that I asked the site author to add for me. (Impressively he added it within a day!) You also get the longest word, which can be helpful too.

If you are more than a casual user, there are very reasonably-priced subscription options, which help support the site.

A note on security and privacy: With sites like this, we always have to think about security and privacy. I’ve no idea whether this site (or any other similar site) stores your text, or does anything else with it. It probably doesn’t, but of course it could. (They do have a Privacy Policy.) So as always on the internet, it’s always best to assume the worst case scenario: don’t go pasting highly confidential documents into any kind of site like this, just to be safe!

How to use readability scores in your writing

Even highly intelligent and/or educated people (not always the same thing!) find it easier to read and comprehend writing that is at a lower reading grade. So no matter who you are writing for, whether it’s doctors and lawyers, manual workers, or the fabled “high-school dropouts”, a lower score is usually better.

The excellent book “Write everything right”, by Denny Hatch, (a long-time marketing man), is well worth a read. (Amazon UK  Amazon US)

It contains these facts from the Literacy Project Foundation, relating to American readers:

 50% of adults cannot read a book written at an 8th grade level

45 million are functionally illiterate and read below a 5th grade level

In other words, the average reading grade in America is 8th grade level. I have no particular reason to doubt that the UK is very similar.

The advice of Denny Hatch, which I agree with, is:

  • Keep sentences to 29 words or fewer
  • Write at 8th grade level or even lower if you can

Conclusion: an essential site for all writers

Here’s a screenshot showing the readability scores for this very article you’re reading now. (Click the image to see a larger version.) What do you reckon? Must try harder!

Readability score screenshot

A “fan” of simplicity

This blog post from Digital Amit is an oldie-but-goodie on a quick lesson in simplicity. This could be a useful story for you to tell when motivating your teams to keep it simple!

It compares two approaches to solving the problem of weeding out an empty box of soap on a manufacturing line.

Of course, you might argue that there should be a root cause analysis to find out why the box of soap was empty in the first place, but that spoils the point of the story!

Problems coordinating your project? Try a short daily stand-up meeting.

This article is very back-to-basics, but I think many people would still benefit from applying it. So here goes!

I was chatting to someone recently who’s involved in a project with lots of different departments within her company, including marketing, IT, finance, and third-party vendors. She said that it’s proving difficult to keep everyone coordinated with the status of the project, and with what needs to happen next. She’s also having problems making sure that all the different parts of the project will be ready by the time they are needed. This has been even more difficult during the summer holiday season, when many people are away from the office.

So what can be done to improve things?

First, of course, there are the standard project management techniques such as a Gantt Chart showing when each part of the project needs to be completed. This could even just be a list that gets pinned to the wall, or put on a website or wiki page so that everyone can see it. (If you’re interested in wikis, I’ve had great success with Atlassian Confluence wiki software.)

But one of the best ways I’ve found to communicate project status is to have a short meeting each day, at the same time every day, with everyone involved in the project. In agile software development these meetings are called Stand Up meetings (or “standups”), because often the participants are all standing up. The idea with this is that nobody really likes standing up, so it keeps people brief and to the point!

The meeting should last no more than around 15 minutes.

Make sure that each person gives an update that includes:

  1. What they did yesterday
  2. What they will do today
  3. Any problems that they have faced that could affect their work (often these are called “blockers”, since they are blocking a task from being completed).

Lots has been written on how standup meetings should work, but it’s really not difficult, so if you’re having problems coordinating a project, give it a go!

Tip for Conference Calls: Ban Speakerphones

One of the big problems with conference calls is that it can be hard to hear what other people on the call are saying. I wouldn’t consider myself to be hard-of-hearing but sometimes I really struggle to hear what’s going on. This is especially true when one or more people on the call are using speakerphones: hands-free phones (that often look like UFOs) that people gather around in conference rooms.

Problems with speakerphones:

  • They pick up background noise
  • They pick up echo in the room
  • People are very tempted to shout into a speakerphone, because they are not physically close to the microphone, which can lead to an unwanted hostile quality in the voice!
  • Volume is inconsistent: speakerphone users are often very loud on the call, or very quiet, or a mixture of both (great to blast out the eardrums of everyone else on the call!)
  • Bottom line: voice quality is usually very poor, so communication is also poor.

One tip I’ve found is to ask participants not to use speakerphones on conference calls. Instead, ask everyone to use a standard phone, even if they are in the same room together. This way, everyone is speaking into their own microphone, which is held close to their face. Call quality is much clearer, and communication is much easier.

The same is of course also true when using Skype, GoToMeeting, GoToWebinar, or other Voice Over IP (VoIP) services.

Ten reasons to use a wiki for documentation

I’ve been very impressed by how useful the wiki has been in real world use: here are the reasons that have made the wiki very successful for us.

Thought Wikipedia was the only wiki? Think again! A wiki can be a great help in keeping all your documentation up-to-date and easily accessible. In this article I’ll explain why you should give a wiki a try.

For a couple of years now, I’ve been working with a FTSE 100 company that uses wiki software for keeping its internal IT documentation. This includes notes relating to development, testing, and how the various IT systems and business concepts work.

I’ve been very impressed by how useful the wiki has been in real world use, so I thought I’d share the reasons that have made the wiki very successful for us (and for me in particular, as a documentation author as well as a reader).

As knowledge management becomes ever more important, most companies should give serious consideration to using wiki software, not just within IT departments but in the wider business.

The wiki software I’ve been using is Atlassian Confluence, but no doubt using other wiki software will realise some if not all of these benefits.

So in no particular order, the benefits that I’ve personally found with using a wiki for documentation are:

1. Easy to find information

A wiki puts information is all in one place and is fully searchable.

With hundreds of topics, potentially written by hundreds of users, it’s easy to end up with a labyrinthine folder structure of Word documents that sit gathering virtual dust because nobody can find them. For example, I had been working with the company for about 8 months before somebody pointed me to some useful documentation that I could have used right from my first day with them!

A searchable wiki makes it quick to home in on exactly the information you require.

2. Easy to tell how up-to-date a document is

I recently read a corporate document, that’s still being issued, that discussed upcoming changes for 2005 – it’s now 2014 as I write this!

A wiki breaks a large topic into a series of sections, one per page, and with automatic date tracking for when each section was last updated you can easily say how up-to-date or out-of-date each individual section is.

If you read a sentence in the documentation similar to “John recently did some work on the payment system”, which is bad because it isn’t specific, you can at least roughly narrow down when this time period might have been. In a Word document that was started 10 years ago and periodically updated, you would have no idea as to even which year it might have been!

Since out-of-date documentation cannot be trusted, and might be either wrong or actively misleading, being able to tell the precise age of the documentation you are reading greatly helps with understanding how much or how little you can trust the documentation.

3. Easy to update, so gets updated more often

Updating the documentation is as simple as clicking the bookmark in your web browser to get to the wiki and making a few changes. There’s no need to fiddle around with version control or re-issuing documentation.

It’s also easy to do a very small change here and there, when you have time, and then build up the documentation over a period of time. I have wiki pages that I update probably once a week as I learn a new snippet of information. This contrasts with the approach of writing documentation into Word documents, where it feels more like you have to write a whole manual or definitive piece of documentation all in one go and then more formally distribute it.

So because wiki documentation is so easy to update, it tends to be more up to date.

4. Easy version control and roll back

A wiki lets you easily go back to a previous version of a page. You can take a more active approach to updating documentation, because you know you can never really break it, and can always roll back if you put the wrong thing in the wrong place.

5. No need for a single document owner

There are no bottlenecks centred around individual people for writing documentation or putting together everyone’s contributions. If you’re reading or reviewing documentation, and you know that something is wrong or out of date, you can update it immediately, without asking permission, and without waiting for somebody else. This helps to keep documentation up to date.

6. See who wrote what

Depending on who wrote the documentation (and your assessment of their competence!), you know more about the likely quality of the documentation, and exactly who to speak to if you have questions about it.

7. Links within the documentation to help users navigate

Being able to easily add links to other relevant sections of the documentation means it’s easier to guide readers to the precise areas of the documentation they will find more useful, and easier to make sure that the reader doesn’t miss other important topics related to the section they are currently reading.

8. See a list of recent edits to know who has been working on what

Atlassian Confluence has a dashboard view showing who has been editing what. It’s like a running commentary showing all the changes that have been made. It makes it easier to see who is working on what areas of the documentation.

9. Notification of changes

It’s easy to set up notifications for sections of the documentation that you are interested in, and then be told when those sections are updated. This way you can be made instantly aware of when important information might have changed.

10. Easy team collaboration for fast-moving information

For sections of the document relating to project status, or what will be released in an upcoming software release, where several authors may all be making changes in the same day, the wiki environment makes it very easy to make and share these changes.

When NOT to use a wiki

There are some downsides to using a wiki, largely relating to making sure that information is kept secure, but any documentation written down can theoretically be disclosed outside the company anyway, so this isn’t an issue solely related to wikis. Wikis can restrict access to certain pages to certain users anyway.

Wikis can tend to be quite free-form, with different authors doing things in different ways, so sometimes you need to try and impose a bit of structure.

If you need full distribution and approval controls, perhaps when issuing documents to third parties, then you might want to consider a fully-fledged Document Management System, but they are quite heavyweight and expensive, and you’re unlikely to really need it.


I’ve found that using a wiki for documentation brings the documentation to life. It’s no longer an old, stale and outdated document that gets written once and then forgotten about, never updated and never read. It keeps the information up to date, prominent, and searchable. I’ve been very impressed with using a wiki, so I recommend that you give it a try.

Action Points

If you want free wiki software then consider MediaWiki, which is what Wikipedia runs on. If you’d prefer a hosted wiki that you can get started with immediately, there are a variety of free and paid services.

Technical Debt: say it like you mean it

When I hear people using the phrase “technical debt”, it’s mostly used as a buzzword. The actual meaning is lost. It’s a euphemism. When they say “There is a lot of technical debt on the project”, senior people nod sagely … and then ignore it.

What is technical debt?

It’s fashionable these days to talk about “technical debt”. If you need a primer on this, Martin Fowler gives a good concise explanation of Technical Debt.

The concept itself is fair enough: each time you hack something into your software code without doing it properly you store up problems for the future, and these problems are added to your technical debt. In that sense it’s a useful way to think about the problem of how a code base gets polluted and harder to work on as time progresses, as the debt either mounts up or gets tackled and reduced.

So far so good. But when I hear people using the phrase “technical debt”, it’s mostly used as a buzzword. The actual meaning is lost. It’s a euphemism. When they say “There is a lot of technical debt on the project”, senior people nod sagely … and then ignore it.

That’s because “technical debt” doesn’t really sound that bad. It’s the same reason the military say “collateral damage” rather than “slaughtering innocent women and children” – it just tends to sound a bit better!

If you could put an accurate financial value on technical debt, as you can with real financial debt, then maybe a conversation on technical debt would have some meaning. There have been some efforts to quantify technical debt, but you might argue that the methodologies are vague and the final numbers don’t really stand up to scrutiny. Maybe they never could.

Technical debt as a euphemism

So what I really dislike about the phrase “technical debt” is the Euphemism Factor, the way it can pull the wool over the eyes of management, and even people on the project, and make them think that things aren’t as bad as they really are.

Let me put it this way. If you were the boss, and a project manager was reporting to you on their progress, what would you think if they said this: “There’s some technical debt on the project, so it will be quite challenging to add the new features.” That’s a phrase I’ve actually heard someone use. And I saw the boss take it, nod his head, and move on to something else.

What the project manager actually meant was, “This code base is so wrecked we can’t do anything with it! Every time we try to add something new, we break a dozen other things. We’ve built fudge on top of fudge on top of fudge, and the whole thing is about to come crashing down around our ears!”

Let’s face it, what we’re really talking about here is honest conversation. Take a look at some of Jack Welch’s books. (Jack Welch was the CEO of General Electric from 1981 – 2001, and is widely held to have been a highly successful CEO). He often talks about the power of being what he calls “candid”. You might choose to call it honesty, frankness, or being straightforward. Or as Dan Kennedy puts it, “No B.S.”

Action points

My recommendation is to move away from euphemisms like “technical debt”, unless you’re attempting to do some kind of serious financial quantification of it, and move towards concrete, specific comments that quantify the problem in terms that are meaningful to the business, and emphasise the potential productivity that is being lost.

So maybe what the project manager should have said was something along the lines of, “Due to the speed with which we’ve had to release new features, and the number of different developers that have worked on the project over the years, the code base has got really difficult to work with now. We’re finding that we break quite a few things when we add new features, so we’re always treading on eggshells, and that slows us down a lot. We haven’t got enough automated test cases to give us confidence that we’re not breaking the old things when we add the new things. So adding this feature is going to take us at least 4 weeks, when if the code base was cleaner we could do it in 2 weeks at the most. The last feature took us 6 weeks, and we think really it should have been 3 weeks, but we broke existing features X, Y and Z in the process, and fixing them took us 3 weeks.”

It takes a bit longer to say, but it shouldn’t take long for the message to sink in!

I’m obviously not suggesting charging in with both boots and telling the CEO in no uncertain terms that we’re all doomed! But what I am suggesting is that you’ll get better results if you move away from vague terms and management speak, like “technical debt”, that can be brushed under the carpet and ignored, and start talking in practical, quantifiable terms about the poor state of your code and how it’s affecting your productivity. Then you might get the chance to do something about it!