Generating a Culture of DocΒΆ

Authors:Leah Cutter
Time:14:00
Session:http://docs.writethedocs.org/en/2013/conference/talks.html#leah-cutter
Video:https://www.youtube.com/watch?v=v41nPTpXnHQ

Leah Cutter is a knowledge management specialist, and has been doing technical writing since 1985. So what does a knowledge management specialist do? She creates a framework for engineer generated content. “I tell engineers what it is they have to write, how it’s going to look, and where to put it.” Less writing, more direction.

Engineer generated content includes comments, READMEs, specs, team sites, wikis, email announcements, architecture diagrams, internal white papers, and internal blogs. Focused solely on internally focused documentation. And even though it’s difficult enough to write external docuemntaiton, it’s possible to develop a culture of doc that makes Engineers willing and interested in writing internal docs.

So why should engineers write docs? Writers are outnumbered; even at Salesforce where documentation is valued, they’re hired in strict ratios to engineers. Knowledge lives in the head of the SME (subject matter expert), and in this case that’s your engineers. But when knowledge comes out of the engineers’ heads, it needs someplace to go to avoid a web of undiscoverable, unsearchable docs. Salesforce created a team focused on internal docs. The Salesforce codebase is currently monolithic, and there’s a single architecture guide for the codebase, for doing releases, servers, etc.

So how do you start developing this sort of culture at your own company? First, harness the power of your internal champions. Find people who are liked minded (engineers who care about grammar, docs, etc), and nurture them and give them a forum. Maybe it’s an email list, forum, or Yammer/Chatter group. Chatter has been great for Cutter because it allows her to put new docs in front of people who care, people who will comment on them, and people who will give feedback. It’s important not to try and go it alone: SMEs know where the problems are, and they probably have ideas about how to fix them. To develop a culture of doc, you need to provide organization and project management so they can help you with documentation.

Cutter’s experience is that SMEs fall into three categories in roughly equal proportion: eager to help, willing to help (with guidance in the form of templates and direction), and curmudgeons.

Salesforce holds documentation hack days, where they focus on fixing docs. They always have a theme, and they always have suggestions about things to focus on. They’ve been very successful and have yielded lots of great resources for supporting engineers in writing docs (example: one engineer started a list of graphical tools for things like ERDs).

They also hold internal architecture reviews where they try to engage engineers with other engineers or architects to cross-pollinate. For example, a cross-functional talk about how releases happen. These help generate a culture of doc by engaging engineers with knowledge sharing.

You as a writer have knowledge that engineers need to help them write docs effectively, and when you share that knowledge you help them write more docs. Hold doc office hours where you’re available to help them with docs. Because some text is better than no text.

Curmudgeons will say “but code documents itself!” Cutter calls “bull”; code only tells what it does, not its intent. [NB: Intent is worthless if the code’s action doesn’t match it.] Even if you know what you wrote immediately after you wrote it, six months later you’ll have moved on and that’s when the documentation becomes critical.

Project Versions

Previous topic

Motivating developers to write API documentation

Next topic

Getting Developers and Engineers to Write the Docs

This Page