Scaling Your Influence Through Documentation
Without writing lines of code, how do you - as an Individual Contributor - become someone who influences the opinions of multiple cohorts of people at once?
Watch
Watch on LeadDev at: https://leaddev.com/staffplus-london-2023/video/scaling-your-influence-through-documentation
Watch on YouTube at: https://www.youtube.com/watch?v=BQ_lKQQcsXw
Abstract
How can you communicate with your exec sponsors, peers and junior engineers and ensure that your vision for the future is reaching your audiences, without spending your days trying to get face-to-face time with each of them?
Once you’ve had your “big idea that you need to convey to everyone” it’s daunting think of the time and effort that would be required from you to meet everyone face-to-face and then repeatedly (and reliably) convey this idea to the in order to reach a common understanding. It’s also high stakes - there’s lot riding on your personal brand and it’s likely to be intimidating and on both sides. Documentation is the way forward. Not technical documentation per se, but artefacts such as guidelines, best practices, decision trees and even full-on white papers.
As an individual your reach might be limited to when and where you are present, but as an author of content you’re able to change hearts and minds while you sleep and reach your audience with your message in a format that endures, at a time and pace that is convenient for them.
In this talk I’m reflecting on my 2 year journey as a Staff Engineer, and how a mix of documentation and working groups has been a surprisingly effective strategy for influencing the opinions of the individual engineers as well as the non-technical stakeholders. We’ll talk about the principles I use to determine ‘good’ and ‘useful’ documentation, some key guardrails to keep your content approachable, and the risks of falling to the dark side - using documentation as ‘proof of work’ or creating the dreaded wall of text.
Slides & Script
I came to a LeadDev conference about 5 years ago, and it really helped me define what I should and wanted to be doing in my career.
You should always try and give something back, so now here I am, and…
I’ve got 25 minutes to talk to you about documentation.
I could stand and preach about documentation and its virtues, but this conference is about sharing experiences, so I thought I’d share mine, my progression, my thinking, my motivations, my lessons.
A question that I get asked is “what do you do all day?”
And depending on our familiarity and their sense of humour, my answer is often “I write docs and attend meetings.”
It’s self-deprecating, it’s reasonably accurate.
I like writing code, I love solving problems.
But most of my deep-thinking time, my effort, the outcome of that is spent writing documentation. And it’s like that because it is effective. It’s impactful. It influences, and it scales well.
That documentation scales is the premise of this talk.
I didn’t start out with the intention of writing documentation.
My career path went developer, senior, tech lead, and then Staff Engineer.
The theme is steadily going from being integral to doing the work, to the more abstract defining and curating the work, and then onto setting the technical direction and talking about more nebulous concepts like “possibilities” and “horizons” and “capabilities.”
For me this is a search for more impact. Impact takes many different forms. Everyone has an impact.
As an engineer, you’re having an impact. It’s immediate, and you see it clearly. You might be a 1x developer, or a 10x developer.
As a leader, directing and guiding others, your feedback cycle is longer and your impact is manifested by the shape of the output of others.
The next logical step for scaling further is working with more people, more teams.
At [Compare the Market] we use the term force multiplier / engineering multiplier to describe these guiding roles. An engineer has a 1x output, but a leader has 0x output, but say a 25% multiplier on the engineers.
So here’s me, a couple of years ago.
Staff Engineer, freshly minted, in my new role, and working with several teams.
Exciting, daunting, and a whole new challenge.
And as I sit there, trying to define what the most important thing I should be doing, how I can have the most impact, I have this revelation…
I came to realise that there was a disconnect between the tech stack we have and its capabilities, and what “the business” thinks we have, and how easily it can do these things.
Sure it “works” today, but it’s not really set up for that future that we’re going to want.
Worse still, nobody else seemed to be doing anything about it and everyone was happy with the status quo.
So we’ve got to disrupt that, can get everyone to understand the need for change.
This is a great project, allowing us the freedom to make broad, impactful changes.
But one thing worries me, and that’s scale, because our organisation and people structure is neither small or simple.
I have my vision of the technical direction - we should go this way.
And for a long time I’ve been spoilt by and used to working with a well aligned technical team.
but now I have more teams, which are new to me and
they don’t all naturally agree
and it’s worse than that, because the audience for this kind of stuff is so much bigger.
Our organisation is more like this. The structure isn’t important, but the scale is.
Here’s me.
I’ve been used to working with or managing six to ten people. And now there’s something like, hundreds overall?
If we’re going to do this thing – this “defining the future tech stack” – and make it a success, we need to convince all of these people.
All of these people are intelligent, skilled, knowledgeable.
They’re all going to have their own ideas, but I need to convince them of mine, and to find a way to change the opinions of this large and vaguely defined cohort.
My existing strategies all rely on things like 1-2-1s and face to face conversations, they rely on fluidity and in-the-momentness, and that’s not going to scale with my ambitions.
So this is the challenge I faced. The creation of Engineering Guidelines for the future.
I realised that I had this extra responsibility to bring more people on board with my ideas, that I had to find a way to change the opinions of a large and vaguely defined cohort of clever, successful, independent and opinionated people, and that most of my existing strategies couldn’t scale with my ambitions.
And my strategies thus far are all based on one on one conversations, which quickly caps out after a certain point.
I am going to win no friends – and importantly, get no traction - if I just do things without involving other people. And the moment I stop, we lose all momentum and it dies.
Essentially, I want to do this piece of work, set a new technical direction, and let others follow through with minimal continual effort from myself.
I did some thinking, some reading, some reflection, and realised this. Influencing – it’s not just for the stars of social media!
Staff Engineers are Influencers.
Influencing is what we do. Influencing is about planting the seeds of ideas or steering people’s thoughts.
This is about technical leadership, and that boils down to deliberately influencing the tech output.
In answer to this original question, what I really should start saying is
I’m an Influencer.
Okay, all joking aside.
I asked myself, how do I become more effective at influencing people?
There’s a few qualities that you can leverage to convince people of things.
- Trustworthyness is a super important.
- Consistency of message and delivering it in an understandable way
- Reliable, accessible, transparent. You’ve got to be available to consult with, show your workings and help people understand the why
- And a constant presence. Not just being there for consulting but also continually gently nudging people and asserting that you exist.
They’re all aspects of building a persuasive case
And I’ve got to do all of that, at this scale.
Scaling your influence is just like scaling any other system, and in this case the bottleneck is you.
You as a system have uptime challenges because you eat, you sleep, you take time off, you get missed from relevant meetings or for whatever reason, you aren’t in front of your target audience at all times.
Perhaps you don’t even know you have that audience.
If you’re anything like me, You as a system have reliability issues, because you forget key talking points under pressure.
You as a system aren’t accessible because you don’t consistently or coherantly explain ideas, or you don’t pitch them effectively for the audience.
So… be less human? Not quite. Be superhuman, metahuman perhaps.
Training AI models might be in our future, but for the moment we have documentation.
Documentation is a great leveller for scaling, because it has all of these things: it’s available at all times and it’s consistent,
Simply put,
Documentation solves everything.
Documentation is a loose word. It takes many forms and purposes.
Text is the obvious one. But in my mind it’s any sort of knowledge transfer that doesn’t have human actively in the loop. Think of videos and screen recordings, or even presentation slides. They’re all documentation. A.k.a. “artefacts”
Why documentation? How does that help?
It replays flawlessly. No accidental omissions of content or different delivery, it’s the same every time.
And those replays cost you nothing
It’s always available. It’s available at 2am on a Sunday morning, it’s available in the holidays, it’s available once you’ve moved on to another job.
It’s scrutable. You can study it at your leisure, in detail, many times over, and it still costs you nothing.
And your mileage may vary on this, but it’s part of our business culture. Organisations differ, of course. But for me at compare the market, documentation is a thing we do, and do quite a lot as part and parcel of getting things done.
So the answer to the “Why Documentation” question is really,
Because it alleviates the burden of being available to repeat myself.
To be clear, it’s not that I stop talking about things, it’s that I stop repeating the same thing each time.
We could all write bad documentation, but what are the traits of good documentation?
We could all write bad documentation, but what are the traits of good documentation?
Consuming Documentation is a different experience to talking with someone, so you’ve got to lower the barriers to finding it.
It’s something that is discoverable and predictable.
We have enough buzzwords and codenames, don’t make more.
Add structure, so that people can skim through and find things.
And give some context and further reading.
To be honest, this is just like internal SEO.
But, what is the purpose of documentation?
Creating docs is a considerable investment of effort, so I want maximum impact from it.
I figure that if I have a better understanding of its purpose and my audience, I’ll be more effective. And if I have some structures or patterns I can follow, all the better, because these are your guardrails and framing tools.
There’s four main things I want to touch on. The first of these is “shaping the future”
This is the fun, future-oriented stuff. This is what our Engineering Guidelines effort became. We want to take all those disparate opinions
And achieve alignment
Lead people on a journey and convert them.
You get the best buy-in, the most constructive challenges, the most fervent supporters by leading people on a journey and converting them.
A structure that we use is largely based around the MDR pattern, or Motivation, Decision, Reasoning.
- Motivation lays out a common understanding, your angle.
- Decision is the assertive “what” has been decided,
- Reasoning is “why”. That’s all you need, really.
If you want to extend this further you can also add “Clauses”, or “things that validate or invalidate this decision.”
You’d do this anyway, right? Make arguments, outline your vision, refine it.
This process will battle-test your ideas, which is an important mental process to work through. But now, we’re writing it down and crafting docs with this intent in mind, so that we can repeat and share and effectively leverage “documentation.”
Documentation of this shape, refined, tested and collated is essentially what we produced and shared to support our goal of changing the technical direction.
Zooming back out…
crystalising the present
We’re not just chasing the exciting future stuff. The shape of today is important, as is making sure everyone has a common understanding.
Language is hard. Understanding is hard. Grasping a concept on the first pass is hard.
Nothing should be implicit or unwritten.
Few people have full context or full understanding of code, or systems, or processes or business motivations.
Crystalising the present is about precisely and accurately capturing the state of today for a common understanding.
And it’s really hard to move forward on that new path without understanding what your starting point is.
And this leads nicely into the next thing, which is establishing trust (and credibility)
Documentation is a form of proof of work, or the extensiveness of your thought process. But outputting documentation - of the correct amount - establishes trust.
It’s got your name on it, right?
Trust in you, that you are secure enough to share it in the first place, and trust that you thought it was valuable enough to commit to record.
And because you created it, or shared it, it becomes a part of your presence, your persona, part of the thing that people understand about you, about the model of “who James is” that they construct in their heads.
And all of a sudden, you’ve gone from being an ephemeral talking head about topics right back around to being someone who creates concrete, definitive and long-lived content on your chosen topic, and you’re now the person who created the source of truth.
“Why Documentation?”
Because it’ll raise my profile. Being honest here. My name will literally be on everything I write.
That’s publicity, and they say there’s no such thing as bad publicity.
Let’s not be shy, to get this job of changing the technical direction done, we need to build credibility and trust. Getting my name out there all builds towards that.
And finally, collaborating and forming connections
Documentation alone is not enough. This isn’t a “build it and they will come” kind of thing.
Writing it down is part of the challenge, and it’s all to easy to spend time writing stuff, forming and refining your thoughts, and then dust yourself off and think “job done”.
Documentation is your starting point. It’s creating the raw material - the next step is leveraging it, getting buy-in and making those changes happen.
Now this is a bit organisation specific perhaps, but within our organisation we use what we call the MDR pattern - Motivation, Decision, Rationale - to frame most of our important decisions, and we have a twice-weekly open forums where topics are brought, discussed and advice is given.
This is one of the best places places to build up credibility and influence with your colleagues. What makes these sessions particularly great is that there’s an expectation that they’re documentation-led, and that everyone speaking is working from an MDR document they’ve created and shared for review before the session takes place, and everyone in the session has read the content before coming in.
Your Mileage May Vary. But this is aludes to the importance of landing your message with your audience and speaking to them in a way that suits their ways of doing things. And the process of preparing the documentation for these sessions cements your understanding.
That’s my key purposes for documentation. I keep that in mind before I write anything, and it frames what I do and how I use it.
I’ve talked very much about how things started out and what we planned to do with our Engineering Guidelines
What I want to do now is change things up a bit and talk about what went wrong and some lessons learnt before we run out of time.
There’s obvious things like your credibility, authority and biases, and how well you structure your content. But those are general things we have to tackle regardless.
The ones that I’ve found really affect documentation are
Lost contexts. We write with assumptions, on a shared system in the open.
I’ve written stuff which tells my own unvarnished truths and caused upset.
I’ve half-written things and shared them early and caused confusion.
I’ve assumed a lot of knowledge and made it available to people who didn’t have that.
Time sensitivity. Everything changes and time progresses, but documentation remains frozen in time.
Crystalising the present really comes with the time sensitivity trap. Things can age quite fast.
It’s our habit to write as we speak, with relative time references like “last week we…” or be vague and write things like “for about 3 months” but these things make less and less sense over time and the audience loses trust. Be specific. After all, how do we know this hasn’t been superseded by new docs?
Similarly, It’s easy to overlook the ongoing maintenance cost of documentation. You’ve spent up-front effort creating documentation and saved yourself repetitive meetings, but don’t forget you are also now responsible for keeping it relevant and accurate. It risks losing impact and die of neglect otherwise.And if nobody reads it, if you don’t spend time throwing it at people, what’s the point?
For a bit of balance then, here’s my top tips [for Influencing with Documentation]
Alright, top tips then.
Start with a template. I’ve mentioned the MDR pattern already. I use that as a starting point for most everything. As part of my template I have reminders to include context, use the simplest language possible and not use buzzwords, so that it’s standardised, discoverable and searchable.
Don’t do this alone. “Working Groups” are a great way to share the burden of effort for something like “changing the vision” and are how I approached the task of creating “Engineering Guidelines.” And as well as giving you extra hands and brains to take on the task of writing and maintaining content, it also gives you new guises you can operate under to enhance the credibility of your output. No more “James says” but rather “the Front End Architecture Working Group says”
Docs are not like conversations, which is good and bad. Pure async and pure sync are both bad, docs drive meetings with prereads, and meetings generate docs.
Share share share. You’re creating documentation as the definitive reference point or source of truth. Find any way you can to inject it into people’s consciousness. We share it on messaging channels, we link to it in our code review process, we deeplink into the wiki pages to support our angle in a conversation.
Iterate towards your goal. Share it early, take feedback, update and refine it. Our first draft of the engineering guidelines, was too short-term and tech specific. So we refined and made them more like abstract principles. But then they were too abstract, so we added detail back in, and so it goes. Iteration creates engagement and a broader audience and helps keep things alive.
Audiences change. Today it’s your team with high context, tomorrow they share it, and that audience has less context. In a week it’s the CTO, in a few more it’s the new hire. In four years it’s either you, or your replacement when you’ve gone off to greener pastures.
Alright then, let’s recap and summarise.
As a Staff+ Engineer you’ve got to find ways of being more influential, and having more of an impact than simply being an awesome creator of code.
- This can mean documentation in the form of written text, it can mean presentations, it can be diagrams, whatever fits your audience and your organisation.
- Nobody trawls through documentation for its own sake, so you’ve got to keep it curated and relevant as a reference point as well as a historic record.
- The docs are always there, so you don’t have to be. Which frees up your time to work on other things. And they take the pressure off you, so you don’t have to remember and reiterate the complexity of each of your talking points every time a topic crops up.
- People, personalities and biases can be tricky to navigate. You can also leverage ownership just like everything else. Much of what we do is about solutions to problems, and we genuinely want our influence to have a positive lasting impact, regardless of whether it’s “James’s” idea or attributed to a collective.
All being well, documented and recorded stuff persists. It persists today when you’re not in a meeting but the people in it have previously seen it. It persists in three to five years time when you’ve switched departments or left the organisation. It persists outside of your head and in the minds of everyone who sees it.
Documentation is a tool you can use to make change happen, but without being a nominal figurehead or spokesperson who has the exhausting task of putting themselves in the firing line each time, trying to reliably replicate a perfectly planned communique. No ego to deal with, no jitters or fear of confrontation, just leading with async communications.
tl;dr (too long, didn’t read)
As an individual you cannot reach larger and broader audiences to “change hearts and minds” without employing a strategy to replace live, face-to-face, interactions. And one of the ways you can do this is by writing and curating documentation.
Documentation is something that you can use to enhance your communication, give it more longevity, more consistency, and make it more readily available.
Creating the written history is your “side hustle”
and it repays dividends in the form of influence.
Presented at
StaffPlus London 2023,