Skip to main content
Anna e só

The way forward: Documentation as the externalization of organizational logic

Organizations should embrace documentation as facilitation device — a foundational link between organizational drive and practice. · 4 min read

This year, we are fastening our seatbelts and bracing for impact as a reaction to a decrease in donations and grant expirations. At a time similarly minded organizations such as Women Who Code and Women in Technology Portland are winding down, we are finding ourselves being more cautious about what projects we fund, and we are turning our attention to fundraising.

As we integrate as a Software Freedom Conservancy initiative, rather than a member project, our roles require more and more collaboration across different teams. And as Billy Joel would sing, we got so much to do but so only so many hours in a day.

When time is so scarce, we ask ourselves: How do we minimize noise and delay while maximizing mutual understanding? We do that by making things less abstract — we use documentation as a facilitation device. A foundational link between organizational drive and practice.

As is #

One of the foundational theories of Strategic Options Development and Analysis (SODA) is Personal Construct Theory:

“It argues that human beings are continually striving to 'make sense' of their world in order to 'manage and control' that world. In this way it implicitly sees the individual as a problem finder/problem solver, using concepts rather than emotion to guide action.” — Colin Eden and Fran Ackermann in SODA — The Principles. Taken from the compilation book Rational Analysis for a Problematic World, Revisited.

SODA embraces individual subjectivity — it sees it as richness, and it’s with that richness we mediate negotiations towards agreeable action. There is no way to go forward without knowing where we are — a step in any direction may result in moving backwards. Organizations which reject documentation are effectively keeping themselves in the dark. We light a match when we ask questions and seek answers. We light candles when we seek consensus, building bridges between different, and often contrasting, perspectives. When there's finally enough light in the room, we can identify points of confusion and points of conversion.

A common concern among administrators of lean organizations is that documentation may become, materially, bureaucracy. I would like to argue that documentation of any type should be seen as the externalization of organizational logic. Documenting ideas, concepts, discussions, and processes is a tool to build consensus from different individual schemas. No organization can move forward without the consolidation of personal constructs into a collective drive.

If we are talking about process management, that's mapping a process as is. Business Process Management (BPM) discipline sometimes call that a phase of consciousness — the organization acquires a functional perspective of what takes place within it, and it can finally manage it. (Remember: Proper assessment of problems like the one described in Dig deeper are only possible if you understand organizational logic and how processes are shaped by it.)

To be #

What is the desirable way forward? What does it entail? How does it relate to the goals of the organization, how does it serve them? That collective, consensual vision guides the way forward. As an administrator, you may have asked yourself, “How do I focus resources on what truly matters?” Understanding a process by mapping it will tell you whether that process is a differentiator or an industry standard — an important step for following a value-driven approach.

“Research has shown that organizations compete using only about 5% of their processes. That is, only 5% of what they offer customers is truly different from their competitors. A further 15% are important core processes that support the competitive advantage (LEADing 2014) (Franz and Kirchmer 2012). This means that 80% of all business processes are routine processes that can be carried out using industry standards or common industry practices.” — BPM CBOK 4.0

For a lean organization like Outreachy and Software Freedom Conservancy, that knowledge is freeing. We don't need to reinvent the wheel. We need to look outward.

I maintain that any conversations about processes as is and to be will be unfruitful without that supporting documentation. More critically, any initiative to create such documentation will fail if we don’t know how to ask the right questions. In the great BPMN Method and Style, Bruce Silver talks about what questions a process architect must ask to subject matter experts:

Such questions evoke cadence and rhythm. They encourage the interviewee to think of a process as choreography, move after move to the beat of a song. It links cause and effect. But something seldom mentioned is the vulnerability within openness.

Through the looking glass #

I try to approach all things in life with the mindset that I always have something to learn from the people I interact with — in passing or permanence —, but I often find that not being reciprocated. In some situations where there’s a clear power imbalance in between, I often observe that being perceived as a learner results in being perceived as the weaker person in the link. To learn is to be vulnerable — to accept there are gaps in what we know and ways we can be better.

It can be unsettling to see someone deconstruct everything you do. They are turning your world upside down, unscrewing every screw, and you would rather be left alone. But I would like to invite you to see this not as a process that demeans what you do, but a process that fortifies it. When a process architect says ‘we can do better’, we are not saying ‘you are the absolute worst’. We are not saying ‘you are not doing enough’. We are coming to terms with the fact we can do our best and that can still result in material losses. We are asking ourselves, “How can we transform this reality? How can we make it better for everyone?” — yourself included.

“When I choose to see the good side of things, I'm not being naive. It is strategic and necessary. It's how I've learned to survive through everything. (…) This is how I fight.” — Waymond Wang in Everything Everywhere All at Once