Did It in Minutes

Some notes on Mo Nishiyama’s talk from Write The Docs Portland

Documenting meeting notes

Excellent release notes, developer docs, and api docs are considered the sports cars of documentation, while meeting minutes are more often considered the garbage trucks: boring, plebeian, and something no one wants to spend much time in. This isn’t too surprising, since actual meetings are often used to catch up on mobile games, napping, or decorating your notes with poo-sketch variations.

To combat the tendency to regurgitate a meeting verbatim (especially dangerous when the meeting itself is uninspired), think of note-taking as curating information instead.

How to move from regurgitation to curation:

  1. Understand your audience. Which stakeholders were at the meeting, and which were not?
  2. Create a shared need by identifying which information is needed most. Chronology is usually the least useful organizing structure. If chronology isn’t critical to understanding, put the most important subject notes first and place them prominently.
  3. WTF (Write the Facts). Avoid the drama of recording every opposing point of view in discussions. Focus on the important facts and generalize the opinions stated.
  4. Engage SMEs. Poll any SME presenter or commenter to get clarification on his or her statements. Identify, clarify, and classify notes of those discussions.
  5. Make action items clear. Define the who, what, and when in order to hold people accountable. If you’re assigning action items, provide the resources to do the work. Negotiate these terms if necessary.
  6. Distribute on collaborative platforms. Avoid email.
  7. Use templates to save time.

Quick tips to encourage readership:

  1. Use easer eggs too combat the tl;dr habit. Reward with things people really want. This trick conditions people to look at the notes you send.
  2. Add humor and personality.
  3. If format exceptions are required (if chronology or verbatim documentation are required, for instance), note these places and give reasons.
  4. Samon pink 16 pt comic sans is a good choice only rarely.

Good meeting notes are a valuable documentation tool, but are a better timesaving tool since they free you from interruptions by people who don’t pay attention in meetings.

Mo’s talk summary is here: <a href="http://docs.writethedocs.org/2014/na/talks/#mo-nishiyama-did-it-in-minutes-the-art-of-documenting-meeting-notes.
Presentation materials will also be posted shortly.

Posted in Technical Writing, Write The Docs

Aggregated Write The Docs Portland links

Daniel Lemke (@RockandRollBot) put together a comprehensive summary of links related to the talks from Write The Docs Portland. Be sure to check out the video links if you missed something during one of the Lola’s Room sessions.

WTD Portland (the ‘My Notes’ links are to a private notebook and are not available).

Thanks, Daniel!

Posted in Technical Writing, Write The Docs

Ignorance is strength: writing documentation by learning as you go

Some notes on Amalia Hawkins’s talk from Write The Docs Portland

The struggle to overcome your ignorance of a subject can be the most creative and productive time in your learning experience. This struggle can help you relate at a high level to your users. In the documentation process, your ignorance isn’t a weakness, it’s a strength.

From her experience hiring a team of teaching assistants (TAs), she learned that the best TAs were are the ones who struggled as students with the course materials. That experience of struggle created empathy with the current class of students; the TAs could understand what their students were experiencing. Positions of inexperience (recent graduate or new hire) are frequently marked by enthusiasm paired with ignorance.

Strategies to overcome ignorance

Read the code. It’s possible to read and study the code to gain a better understanding of it, but this solution can only tell you how and what, not why, the creator’s intent, or the expected use.
Ask around. You can also put questions to team members to help improve your understanding. This approach can also close the what and why gaps, but usually fails when the questioning turns to why.

Her own process to obtain information about the database Context involved struggling alone for 2 weeks, before interrogating the CTO for 10 minutes. While it was effective for her, this process is not replicatable. The experience of it prompted her to write a rant about the pitfalls she encountered, which became the beginning of an internal onboarding document for that code base.

What she learned

  1. Write anything as a start (even a rant). It’s better to write something wrong than continue with nothing. Places for improvement and correction can be identified through peer review.
  2. Find your allies. If you’re confused, other people might also be. To cast a broad net, make your document accessible to everyone and available for casual imput.
  3. Spread out the work of creating internal documents. The work should consist of 3 distinct parts: content creation, formatting, critiquing. The goal is to make the docs usable by making them accessible; sidestep the constraints of format to get the information distributed. Let developers and engineers focus on critiques.
  4. Importance of internals. A lack of internal documentation can negatively affect the ability to scale. Without these docs, onboarding and training happen more slowly. The lack also affects horizontal growth by impeding communication between teams and across geography.

Questions from the audience

  1. Can we get a copy of the rant about the database Context?
    It’s possible to publish an excerpt, although it should be noted that it’s not representative of permanent mindset.
  2. What does the process for moving between internal docs and public docs include?
    Mostly cleaning up tone for consistency and additional standardization from the documentation team.

Amalia’s talk summary is here: Ignorance is strength.
Presentation materials will also be posted shortly.

Posted in Technical Writing, Uncategorized, Write The Docs

There’s a new sheriff in town

Some notes on Heidi Waterhouse’s talk from Write The Docs Portland
When you’re the new sheriff in town, how can you establish order in a chaotic environment?

Get a star

Get hired. That act conveys your authority. Hold it in your heart; no one believes in documentation. You are in your role, on the team because you already bring value. You are an expert. Use your authority to get documentation out of individual heads and onto paper (or web or integrated or wherever).

Set up shop

It’s essential to know where all the people and things are.

  1. Make a seating chart of the office. Locate and name people and their specialties.
  2. Draw a map of the existing docs and how to get them. Then, get access to them; you need to be able to see everything.
  3. Get to know the neighborhood. Read everything you can find about your competitors and users. An optimal time to do this is while you are waiting on your permissions.

Draw fast

Be ready to defend and expand your territory.

  1. To skeptics, note that you are better and cheaper than docs written by developers.
  2. Postpone investment in frills until later. If no one can use your docs when they need them (now), they will start going around you.
  3. Deliver early, deliver often, or talk about why you can’t deliver. Show your value early.
  4. Address emergencies first to garner trust. Develop precision (formatting, readability, localization) between emergencies.

Save the townspeople

Establish your value and intent early by helping someone who really needs your unique skills.

  1. Find and help fix the biggest internal pain point belonging to your dev or service team.
  2. Create a structure to ask questions and receive feedback.
  3. Treat docs as code, including bugs, issues, and code visibility.

The townspeople who are under your care comprise a broad category. They may not be part of an expected group.

Check for scorpions

These dangers are situations, not people. They can include hoarded documentation and stuff left over from the last sheriff (what? you thought you were the first?). Examine the hoarded and leftover stuff, then isolate what’s useful. Next, deputize the vigilantes and bring them into your work. The vigilantes are people who have demonstrated their interest by hoarding docs. Take this opportunity to improve collaboration by making them part of the team; put them in charge of proofing and take control of their source.

Build infrastructure

Build the systems that facilitate your future progress.

  1. Structures for everyday life, including templates to streamline and standardize work. Do this 6-9 months after assuming your role.
  2. A newspaper, or, release notes. This ensures that documentation becomes or remains an integral part of the product.
  3. A telegraph, or, channels of communication. Talk to other sheriffs of other towns and find peers who will support you.
  4. A plat, or, map of documents. This can help you find gaps in your docs collection. Designate spaces for specific purposes, including these essentials:
    • customer use
    • configuration
    • advanced user customization
    • fixes and troubleshooting for everyone (people will create fixes if they don’t exist, but better to make and control this)
    • reference guide

    Set aside specific sections for future use even if you don’t have docs for those places yet.

Plan for succession

Move docs off personal computers and out of locked repositories. Make docs part of the code base and use the versioning and submission requirements of the code base.

The sheriff is part of a town

A sheriff is part of the community, is invested. A Texas Ranger, by comparison, comes to town for a rescue and then leaves. Be the sheriff, not the ranger.

Questions from the audience

  1. What is greenfield documentation?
    When you walk into a pasture and it’s unplowed, untouched, nothing exists, that’s a greenfield.
  2. What are your favorite techniques to reestablish communication when legacy resentment exists?
    Address pain points first. Be an active listener. Install a working environment with Dev Ops to create onboarding documentation, which will add value to Dev Ops.
  3. Heidi’s talk summary is here: The New Sheriff in Town: Bringing documentation out of chaos
    Presentation materials will also be posted shortly.

Posted in Technical Writing, Write The Docs

Communities are awesome

Some notes on Ali Spivak’s talk from Write The Docs Portland

As a nonprofit, the The Mozilla Developer Network (MDN) relies on community of volunteers to create and maintain developer documentation for all Mozilla products. MDN documents are used by approximately 2 million developers per month, translated in 35 languages, and must respond to continually evolving development standards.

How it all gets done

MDN maintains 5 full time paid writers and 2-3 part time paid contractors. Full time writers also work with the MDN community to fill in the documentation gap. This community involvement permits MDN to provide a quantity of work that would normally require a much larger staff. The community consists of: 220-225 core volunteers, 600 active contributers (making one edit per month), 1500 semi-active contributors (making an edit within the past 3 months), 5000 registered contributors (making 1 edit within the past 3-4 years), in addition to passive readers who will hopefully add future content.

Contributions from the community

What the community does:

  • writes articles
  • edits (typos, grammar)
  • translates
  • provides tech reviews
  • adds tags for search
  • builds IA
  • represents at events
  • participates in localization sprints

Just as important as the actual work provided, the community also contributes valuable perspective. Because the community is distributed and global, it contains multitudes. A broad array of perspectives is available to identify issues and concerns relevant to a varied group of users. For example, users in rural areas of India might identify low bandwidth as a limiting concern, which is not usually thought an issue in the Bay Area.

The awesome herd of cats

Community developers and members continue to volunteer–give away their free time–in exchange for the benefits that are experienced by being part of something greater. The strength of the community is built on this sense of belonging and on the assumption of trust and respect that community members are given. The access granted to the MDN to equates to this assumption of trust and makes the act of contribution more accessible. Together, access and the act of contributing create a sense belonging.

With this respect given, members feel a sense of responsibility, as evidenced by low incidence of spam. But given these benefits to the individual, how does a community manager direct the work of the minions? The answer is, you don’t, because they aren’t minions to be directed, but really more like a herd of awesome cats. As a manager, your job is to help and motivate them, provide status, and create opportunities for them to provide their expertise. Volunteers don’t need people telling them what to do.

Why do people become part of an awesome herd?

Science can provide some insight into the reasons that people sign up for this level of volunteer commitment. Research of human motivations compares extrinsic and intrinsic sources of motivation. Extrinsic (outside rewards) have been shown to demotivate individuals as those rewards replace the intrinsic (internal) motivation experienced from completing the task itself. Intrinsic motivation generates meaning. MDN volunteers are motivated by being part of something larger, making contributions, learning with and from others. These motivations give their efforts meaning.

MDN and Burning Man

How are they similar? Both motivated by:

  • autonomy (desire to direct one’s own life)
  • mastery (an urge to get better)
  • purpose (work for something larger than self)

In both communities, 90% of the work is achieved by volunteers. Additionally, the principles of Burning Man are similar to principles Mozilla emphasizes, such as: radical inclusion, gifting, decommodification, radical self reliance, radical self expression, communal effort, and 3 others I didn’t catch.

Interchangeabilty of community and culture

Zappos core values underpin their community and their culture to the extent that deviation from them can mean employee termination. What principles are don’t matter in this example, what matters is are they adhered to? The key to building culture lies in the principles that keep people together.

In MDN, the principles that attract and reward are the reasons behind formation of its volunteer community.

It’s not built to get easier

It’s not easy to remain an open community committed to bringing people in from outside. MDN roadmap and goals are developed by Mozilla with the community, instead of for the community. This requires much more work and communication than imposing a structure from “above”. If a manager of the community can’t convince the volunteers that something is the right thing to do or direction to take, maybe it’s not right.

A community that contains a diversity of perspectives and needs is one that is already providing feedback about what is most important. It’s essential to break out of the managerial bubble to make decisions based on what’s right for the community.

Consensus occurs slowly when working with a large volunteer community, but doing the wrong thing is slower overall. Once consensus is achieved, progress occurs incredibly fast. It’s more beneficial to experience lots of upfront churn. You want your churn early.

Ali’s talk summary is here: Communities are awesome
Presentation materials will also be posted shortly.

Posted in Technical Writing, Write The Docs

Flow: a permaculture approach to documentation projects

Some notes on Homer Christensen’s talk from Write The Docs Portland

Homer Christensen practices permaculture, which is a landscape philosophy that advocates working with rather than against the natural evolution of a place.

A landscape philosophy

Permaculture as a landscape philosophy adheres to these tenets:

  • Design to work with rather than against nature
  • Identify what constitutes “with nature” through practiced and thoughtful observation
  • Observe entire systems and their functions
  • Permit systems to direct their own evolution

Co-developers of the permaculture concept, Bill Mollison and David Holmgren, based the permaculture system on observations of indigenous cultures’ relationships with their environments and ethical concerns for people and nature. The system they developed:

  • Works with natural elements
  • Achieves stability through diversity
  • Locates solutions within the identified problems
  • Exerts the least amount of energy for the greatest result
  • Catches and stores energy (momentum)
  • Is resilient and easily maintained
  • Centrally locates care for the Earth, care for people, and fair share (fairness)

A documentation philosophy

A permaculture method of documentation borrows from this philosophy, particularly the ethical underpinnings. Respect for readers and users, people on the team, and the project effort is essential to the success of the entire endeavor.

A permaculture documentation pattern can be summarized as:

Observe > Design/Build > Evolve

Effective observation must occur free of preconditioned ideas and with an open mind. In this state, without outside patterns or systems of thought imposed, the observer can more easily note the ideas that draw attention and the information received.


Open observation can help answer these project questions:

  • What patterns and flows of energy exist?
  • What distinct phases exist?
  • What resources are need and for what duration?
  • What is the desired yield (outcome)?

Answers to project questions are based in these planning patterns:

  • Which team members are available?
  • What are their skills, abilities, inclinations, and paths of growth?
  • How can these individuals be combined to form an effective team?

Natural human proclivities and team dynamics are living systems with their own functions and evolution. Additional awareness must also be given to the project scope, timeline, and culture.


This segment of the pattern helps identify what you want to do with your project and how you might get there.

Design/Build should:

  • Identify zones of access
  • Work with and not against energies
  • Make small early changes to effect greater later changes
  • Recognize the value and resilience in diversity
  • Encourage collaboration and cooperation
  • Stack functions
  • Design for multiple yields

Recognize that much of the action occurs at edges, where lots of diversity exists. Here different teams come together outside normal isolated spaces. To achieve most efficient communications between multiple teams and individuals, spread out edges and increase their surface area.

Zones of access are places where people gain access to information. These zones open to a reader the information that he or she needs to know. These zones should also provide information about which information is accessed most frequently.

Design/Build should emphasize cooperation, not competition, as the basis of the system. Collaboration within and among teams can improve stability. can be fostered through increased communication and chunking information sets for appropriate reuse.

Sometimes the urgency of direct action overshadows a collaborative process. This is a common danger to a collaborative system and should be confronted through group engagement and connection, which will likely achieve greater success. (Paraphrased from Richard Telford)

Documentation design that uses a permaculture philosophy:

  • Provides what the reader needs most frequetly and urgently; makes it easy to find.
  • Increase the edges where collaboration happens
  • Distributes and chunks work to reduce risk
  • Assigns work based on abilities, not titles
  • Takes opportunities to make early efficiencies
  • Uses single source and source reuse in docs and among teams


The documentation system will evolve. Don’t attempt to restrict it in stasis. Let the system evolve. Things you can do include:

  • Continue observation
  • Develop the “soil”
  • Refine the system
  • Maintain a feedback loop

Development of the “soil” is development of the most valuable asset in your project: the people. This development should help your team evolve, gain new skills, and assume tasks that will assist in their growth.

As the system evolves, so will the documentation. Lessons learned provide information about where evolution can or should occur. Measurement and evaluation of the documentation at the end of the project can identify other areas where evolution might occur. Avoid impeding the evolutionary development by remaining open to new ideas, training teammates in new skills that address developing needs, and by making free exploration time available.

Audience Questions

  1. When relating anecdotes about the improvement in team morale during a period following structural upheaval, did the change in tools used play a role?
    Originally documentation existed in MS Word, created by instructional designers. Help was created in MCFlare. A disconnect existed between documentation and training teams. Information was not shared; roadblocks existed. When personnel obstacles were removed, we could bring teams together. All content was then created in MCFlare, reused and treated as one entity.
  2. What are the challenges of establishing a permaculture philosophy writ large in a toxic environment? How well does this approach scale? Can it scale horizontally across products? Without leadership commitment, what is the role for an individual contributor in such an environment?
    Individuals can establish connections, develop avenues, and express needs and desires in their pursuit of a systemic philosophy of documentation. Single sourcing can be argued to management as an efficienct, lower cost solution. In the earlier example, the personnel transition created an opening for change, but he total time to establish and implement the change was 18 months.
  3. As a team manager, what arguments and strategies do you use to acquire space and time for your team to implement this philosophy? Is it more effective to use the language of cost savings than it is to appeal to market competition?
    Yes, avoid speaking of competition; use language of efficiency. Argue that increased avenues of information flow make the project more stable and resilient. State that a cross-trained team is stronger and more efficient. Point out that when cross-trained, individuals do not become blocks. Encourage reciprocation of assistance among team members.
  4. To reiterate: Observe, Design, Evolve

    Homer’s talk summary is here: Flow: a permaculture approach to documentation. Presentation materials will also be posted to that same page shortly.

Posted in Technical Writing, Write The Docs

Write The Docs

I’m in Portland for a couple of days this week, attending the Write The Docs conference. I’m excited to meet some talented people, roll around in their ideas, stuff my pockets full of smartness, and take it home to use in my work. In exchange, I’ll share what I know and take good notes.

Posted in Technical Writing, Write The Docs
In Archive