Why You Should Write More Documentation

Documentation. Collectively, we should all write more of it. But why don't we, and why should we write more?

Slides

Okay, let’s talk about Documentation.

But first…

Hi, I’m James.

I’m a Staff Engineer for the Journeys Team, and

I have a Web / Front end background

I’ve been doing this since I rolled out of Uni.

None of which is relevant to the talk, other than to set the scene a little.

In the interests of setting the scene, I want to talk about the Staff Engineer role, because that’s not quite a common term you hear and because of that it leaves people politely confused.

[I cribbed this off our own CTM website blog.]

This is where the Staff Engineer sits

A Staff Engineer is what we call an Individual Contributor role. Which is to say, it’s usually a technical role, and it’s a role that you can progress into in your career path, without having to take on the dreaded “Line Management” or “Manager” responsibilities.

The job is all about stepping away from code and day-to-day operations, and worrying about elevating things like quality, focusing on system design, the shape of the technical solutions and the path ahead, without being responsible for people and their professional development, or the near-term delivery of a project.

So that’s my little introduction, and where I’m coming from.

It’s an Icebreaker, get it?

I’m going to start with a bunch of questions - which you don’t have to answer out loud - to get us started.

Mainly aimed at Software Engineers, How many of you:

  • write code?
  • work with code that others have written?
  • have ever been confounded by some code - your own, or someone else’s?

For Architects or Systems / Solution people, how many times:

  • have you explained an idea to someone, and they’ve not quite
    understood it?
  • have you had to repeat something, either to different groups, or to the
    same person?
  • how often do details get missed or misinterpreted?
  • have you forgotten some nuance of a solution?

For Project Owners, Business Analytics, Roadmap and Delivery people:

  • how do you get your source of truth for deliverables?
  • how do you explain your business cases?
  • how do you win support for things?
  • how do you reach a common understanding?

For the Visionaries - all of you - regardless of role

  • how do you make this thing you’re doing last beyond you?
  • what happens when you’re away? when you’ve gone? when you’re
    unable to steer the ship?

Okay, let’s talk about Documentation. With that exercise we’ve established that we need documentation.

Documentation is a little bit about being a good citizen, about doing “the job” properly and methodically and completely, and being respectful of the needs of others and our future selves.

And yet, Documentation is a thing that’s an oversight for a lot of people. That’s understandable.

As an Engineer, I understand why doing the documentation is one of those jobs you kind of “sigh” about.

I write code, I solve problems. I get that instant “feedback loop hig|” when I do some code and it works.

And I don’t get that same immediate rush from writing
documentation. Documentation is fuzzy, it’s hard. I write it, and eventually, someone will read it. Hopefully. Crucially, the feedback loop is long, so I get no rush from writing documentation.

If anything, documentation feels like unnecessary grandstanding. I wrote a thing – here’s how you use the thing! Look at me!

But for all that, Documentation is important.

It is not - should not - be the case that Documentation is “only for technical manuals.” Documentation is the artifacts that are left behind in the wake of work.

Technical documentation is a thing, Operations manuals are definitely a thing, but I’m not talking about them.

Documentation applies to everything, anything that’s not ephemeral or lost as soon as it’s broadcast.

It’s the README yes, it’s the code comments, but it’s also the decision records or the business cases or the market research insights and all of the stuff that goes into convincing someone.

So how do we get someone to write more documentation?

You give them some motivation. Oh sure, you can mandate that people write things down.

But that’s not as effective as giving them a selfish reason to do it.

Those questions I posed at the start, hopefully they’ve done their job about convincing you why you’d want someone else to write documentation.
I’m going to talk now about some of those selfish reasons why I would advise you to write documentation.

These are broadly:

  • Conveying ideas consistently
  • Influencing more people
  • Becoming immortal

Sound good? Stay tuned for the clickbaity source of immortality!

Technical details are the dry stuff, the absolutes. But a lot of the time it’s the motivation and the inspiration or aspirations that are more important.

Sharing ideas is hard. They’re like stories, and they evolve and mutate over time and with each retelling.

Whenever you share your ideas, your audience hears and understands something a little unique.

Perhaps you over-emphasised a certain point, or skipped another. Perhaps they misunderstood something. Perhaps your idea has evolved from the last time you shared it with someone, perhaps you forgot some crucial detail.

Maybe things just get forgotten. But one thing is for sure - if you don’t write it down, it will eventually be forgotten. So if you want to be consistent, if you want to seize the narrative, you need to write it down.

Once it’s written down, it doesn’t matter if there’s deviations or omissions or misunderstandings, because there’s now a definitive a source of truth. Documentation is flawlessly and effortlessly repeatable.

And nobody says it has to be perfect on the first iteration and locked-in for all time. You can revise and update the documentation, you can engage with people and ask and answer their questions in the document as time progresses.

Everything you hear, you talk about, influences you and everything you talk about influences others. That documentation you wrote down influences people.

But the real superpower is availability.

You can only be in one place at a time, having one conversation at once, presenting in one room at a time.

But documentation doesn’t have that replication limitation. You write stuff down and share it with the world, and it’s available all day, every day.

You make a persuasive argument, your pitch, your technical documentation, your manifesto for changing the entire codebase, and it’s there and waiting for people to read. Your ideas can simultaneously be in front of the eyes of hundreds of people in your organisation, all at the same time.

And it’s there in a format they can consume, at a pace they can consume, when they’re ready to hear your message.

But it’s also about your legacy, and alignment with the vision today and tomorrow.

Apart from the free bar, the moment you’ve all been waiting for…

You see the thing is, everything I’ve said about conveying your ideas and influencing people, it’s not just about today, or here and now.
If you write the documentation, it has the potential to be something that lasts for a long time.

No more of the have a meeting, and leave the room, and everything has forgotten these wonderful ideas.

There are bits of documentation - important bits of documentation - which have lasted for (in some cases) almost untouched for 8 years. They are the comprehensive and definitive sources of truth in some areas, and the person that wrote them has been gone for at least 4 years. But we still know their name, and we’re still following the groundwork and guardrails that they put in place.

If you’re on this mission, you genuinely want to see things change a certain way, you cannot do everything on your own, so you need to document it and pass it on.

Okay, I had to get that quote in here because I cut it from the longer form version of this talk.

The point is, your impact isn’t limited to the time you’re here. Immortality is about persisting, and creating or doing things that have a lasting impact.

And documentation is a form of persistent influence, which shapes the world that comes after you – regardless of whether you’re there to see it.

  • Not to sound morbid, but you won’t always be around to share the knowledge personally,
  • You can’t reach everyone at a time and headspace that suits them,
  • You’re human and fallible and are allowed to be imperfect at communication or consistency or take time off or change team.

So write it down, and make life easier for everybody.

My three takeaways are:

  • Consistency
  • Reach
  • ~Immortality~ Longevity

This is about others, but it’s also about you - think what you’d be able to achieve if you could just palm people off with documentation each time instead of repeating yourself - think what you’d be able to achieve with all that extra time!

Finally, a plug for my longer-form presentation, which you can watch on YouTube:

https://www.youtube.com/watch?v=BQ_lKQQcsXw

Presented at

  1. Agile Peterborough
    Agile Peterborough,