I’m at Write the Docs today in Portland and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
Homer started the talks on Monday morning. His talk centered on flow and using permaculture principles to conduct documentation projects. Homer works as a technical writer, and has for about 25 years.
Permaculture is a word coined from combining permanent and agriculture. It’s primary use is in landscape and agricultural systems. While that’s where it began it’s spread since then. Bill Mollison was teaching permaculture in Australia during the late 1970s. It’s about work with nature, of protracted and thoughtful observation, and of allowing systems to demonstrate their own evolution. There’s a lot of space for allowing; there’s direction you do but not commanding.
Homer redid his backyard on these principles, ripping out a sterile grass environment and planting over 30 fruit trees. He’s now got a fully functioning ecological environment behind his house. The lesson is that diversity gives stability; ultimately the problem is the solution.
So, how does that relate to documentation principles? First, the model Homer works from in his docs is one of observation, design, and then evolution. Design may be where the bulk of the effort happens but everything starts with observation.
Observation, based on these principles, is without preconditioned ideas. You look at things with an open mind. As Homer said, if you feel like something is missing, spend more time observing. For documentation this means looking at things like flows of energy, existing corporate culture, the resources you need to complete the project, who’s available to help with it, the strategy to re-use resources throughout the company, and much more. Ultimately we want to discover the patterns of the organization, team, and readers. This is a phase we frequently short-change or skip all together in projects.
Design, then, is looking at zones of access. You make a small change early to create the largest effect. The edges of spaces are where the action happens; it’s where the energy is exchanged. In projects you want to design for collaboration and cooperation while yielding multiple things. Zones of access are where you can gain access to information. You can answer questions like, what does your reader need to know? What do they access most frequently? And, how can you help them? Cooperation does not mean competition; cooperation is about sharing information, chunking tasks in to specific buckets that can be distributed across a team. It’s something that’s frequently ignored in projects due to the urgency of direct action.
Evolution is knowing that your system will evolve and letting it. You continue to observe, refine your system, and keep a feedback loop in place. Growing your soil, or foundation of people, is crucial. This is the most valuable asset you have for continued evolution. For documentation you need to measure and evaluate while being open to new ideas. Training your team on new skills to fill needs helps, too.
A permaculture approach can be used to plan, design, and execute a documentation system or project that can be deployed across an organization.