Skip to main content

Attend to the work

· 11 min read
Liz Argall
Liz Argall
Technical Writer and Program Manager

This essay started as a love letter to mindfully turning up. I wanted to write about the power that comes from turning up a little bit at a time consistently. As I attended to the work of blogging regularly it evolved to be a love letter to processes, structures, systems and their interconnections. This essay gives you a tour of philosophies and metaphors that may feel disconnected at first, but all feed into creating meaningful, effective work while avoiding burnout.

Due to the nature of this essay, I've only done minimal edits while typing. This essay is a love letter after all, and it wouldn't do to over work it!

Let's begin​

Over the last few blog posts, I've shared some resources for mindfully turning up for your docs and for yourself.

If you look at these resources you might get a sense of overwhelm. OMG, there's so much to do and I haven't done it all! It's easy for your mind to shut down and decide, if you can't do it all, what's the point?

All of these resources have evolved over time, through a combination of trial and error, research and reflection. And so it should go with your implementation. All of these structures are there to foster better conversations and give you different ways of focusing your attention through different helpful structures.

If you glance at the templates briefly, perhaps that sparks an idea or irritates you in an interesting direction. When we mindfully observe and work through patterns, templates and philosophies with a curious mind it can enrich many domains in our lives. I'm a better Aikido practitioner thanks to how deeply I care about technical writing. I am a better technical writer and colleague by thinking about how I can apply Aikido to the workplace.

The joy of mindful practice​

In Bounce: the Myth of Talent and the Power of Practice, by Matthew Syed, Syed reflects on how so much of what we perceive as talent is practice that we don't see. Sometimes we don't even see our own practice, because it's "just fun" or we don't see how expertise in one domain can contribute to another.

In Bounce, Syed explores how it's not just any practice that helps you grow. Syed was the number one table tennis player in the UK for many years and was an Olympian twice. When he goes through his own origin story he explores how a series of happy coincidences created an environment where he was able to practice with pleasure from an early age and then have the chance to train with technical rigor at school.

Doing just any old practice won't make you an expert. If you practice half-heartedly doing something, 10,000 hours won't feel like expertise, it'll feel like a chore and you'll become an expert at drudging through something with diminished attention.

I'll never forget watching Richard Sherman, a remarkable American football player (if sadly in the news for the wrong reasons these days), warming up before a game. It was the best part of the whole day. While other people were going through the motions doing warmups to get through warmups, he was giving every motion his full attention. Every lunge, every rotation of his body, committed fully to the exercise and not bouncing out of it before completing the full stretch. His focus and ability to use this "simple" task to work with every part of his body is a memory I treasure and carry with me into my practices.

When Richard Sherman warmed up he aligned his consciousness with his body with his activity, filling it with intention and power. It's not just how much we practice, it's how we practice.

The pleasure and purpose of organizing philosophies​

Aikido has been a love of mine since I was 19 years old, and I've been with my present dojo for about a decade. When I bow in, I try to empty my mind, splosh out all the stuff that's been building in my head. I set an intention to be present for what that practice is and to learn deeply, whether we're doing a "basic" technique or an advanced move.

Emptying my head helps me be present for my fellow Aikidoki as they are, not what I think they are. It helps me listen closely to newer folks, their struggles teach me so much about my craft, as new users and new minds can help me learn about my docs. Emptying my head and staying grounded in my practice helps me listen closely to the folks who have been around longer than me, my subject matter experts (SMEs). Sometimes I might be baffled about how they're trying to teach me something. If I listen closely and remain open to their teaching I can find out if they're actually trying to teach me something else. Sometimes I see how the struggles of old hands are similar to the struggles of newer folks. We can laugh at the commonalities, how we all benefit from returning to the beginning and always working on our foundations.

Through the constraints and structures of practice, it happens at a certain place at a certain time, our techniques have a shared vocabulary and certain people lead the experience, I have an organizational structure to actively learn in. No matter what we do at practice, I'm doing Aikido with my whole attention and that is satisfying.

When we mindfully turn up and know we are operating in a helpful structure, we can set aside (or turn down the volume) on a whole range of worries and perfectionisms. The question isn't, "Am I good enough?" The question becomes, "Am I doing Aikido?"

We can see the value of helpful structures in so many fields and amongst so many people who perform at high levels. We can see these helpful structures in the ways we build communities and interact.

Permaculture design principles​

Permaculture, a philosophy and practice for sustainable land management and communities, posits the questions such as:

  • Am I listening to the ecosystem?
    • Am I trying to force my will and how "things should be" onto documents or architecture without working through what that means for that workplace and userbase?
  • How can I obtain a yield?
    • Am I getting caught up in elaborate structures when I should be focused on smaller user stories?
  • How do I use edges and the marginal? How am I catching and storing energy? Are we paying attention to the correct level of design?
    • Do I need to educate people that messy is ok, especially in forming and storming phases?
    • Do people feel safe contributing and that mistakes and imperfection are ok?
    • Am I getting bogged down in copy editing perfection when that time would be better served working on the big picture?

Diataxis framework​

Permaculture can then blend into the Diataxis framework, which isn't about bludgeoning documentation into a specific shape. It's a map that helps you articulate natural rhythms that are pleasing. Diataxis can help create clarity around:

  • The purpose of each nugget of information.
  • Developing a consistent template for readmes and features.
    • I find I apply all of Diataxis on a single page, far more than splitting things out.
    • I've found engineers find it easier to align with a template if there is a methodology behind it, it's not just me having ideas.
  • Trust that messy and incomplete is part of the process.
    • Permaculture is a valuable framework, but it's nice to have a call to authority that says, "Things looking bad can be a sign of improvement."
  • SMEs can find it easier to onboard people and manage the OTT infodump if you tell them their deep understanding has a place.
    • I've used Diataxis and the "teaching someone to cook" metaphor to help SMEs understand that there is a time and place for explanation, but first we need to get folks into the kitchen.
    • Saying how-to guides are like recipes has helped SMEs understand when a tutorial is required and when it's a how-to. This clear distinction has made it much easier to build trust, as programmers fear being patronizing or being patronized to. Don't worry, I wont tell you to wash your hands when it's a recipe card!
  • The best fertilizer is the gardener's shadow.
    • Ok, that saying is taken from gardening, but at its heart, Diataxis is just a framework for mindfully turning up for your docs and improving a bit here and there.
    • It's a continual practice, not an end point.

Open source principles and values​

Diataxis can blend nicely into open source principles such as do-ocracy, collaboration and self-organization (how you turn up for your part of the garden might be really different to mine, but we both want it to thrive and a shared vocabulary helps). Open Source can invite questions such as:

  • How are we listening to our communities?
  • How do we build environments of collaboration and respect?
  • How do we support the do-ers and make sure we're not burning through volunteers?

Agile methodologies​

Open source blends nicely into Agile methodologies, where a few of the questions it asks are:

  • How are we creating chunks of work that are purposeful?
  • How are we collaborating cross-functionally and with our customers?
  • What can we achieve now?
  • How are we valuing the energy and time of all the individuals that make up the whole?
    • As Permaculture would say, "Use and value renewable resources and services"

Spreadsheets and processes to value your efforts​

The spreadsheets I've created should have value if you glance at them. They should have greater value if you use them as a structure.

In Aikido, I know that if I've turned up on the mat and given my focused attention for an hour, I have done good work.

If I spend an hour working on a search term analysis, I will have done good work. I may have improved my docs, gained a greater understanding of user experience or experienced great waves of despair as I encounter places my docs fall short. What matters on a fundamental level is that you've practiced within a supportive framework and have turned up.

If you don't have a structure it can be easy to think, "What have I done? I've done nothing today!" This is especially true if you encounter problems in the docs thanks to your diligence. When you don't have a container to hold and witness your work it can be easy to lose perspective.

The map is not the territory​

Various helpful structures can help you see your content in new and novel ways. They can disrupt comfortable modes of seeing and get you closer to the experience of a new user. They are helpful maps, but the map is not the territory.

Maps can be helpful for pointing out phenomena in our shared physical universe, but they are always incomplete. They have to be, or we'd be drowned in noise. One map might be full of contour lines and show where dry riverbeds sometimes flow. Another map might crisply and cleanly focus on roads and provide the latest prices at gas stations.

Neither map is wrong, they just have different purposes. Sometimes, the most beautiful thing as you explore the territory is to see what seemingly disparate maps have in common. To attend to the work, to gain experience, to think deeply and see how your maps build into a larger story is satisfying.

Media I'm enjoying​

Want to read more blog posts?​

Subscribe to my newsletter to be emailed whenever I do an update!