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.
Leah kicked off the afternoon sessions by talking about how you can encourage engineers to do the “write” thing. She focused on discussing the ideal. Not everything she covered will work but it’s a starting point.
Leah is a technical writer who is a Knowledge Management Specialist at Salesforce. She’s been working as a technical writer since 1985. As she phrased it, it is her job to generate a framework for engineer-generated content. She tells engineers what it is they have to write, where they have to put it, and what it should look like.
This engineer-generated content includes code comments, README files, specs, team sites, wikis, email announcements, and much, much more. You’ll notice external, customer-facing documentation is not on that list. That’s intentional.
By primarily focusing on internal processes you can create a culture of doc in your company and among the engineers.
Writers are outnumbered by engineers. Even at a documentation-strong company like Salesforce writers are just a small fraction of the workforce. By getting them involved you increase your ability to document things.
Within a company your knowledge exists in the minds of subject matter experts. These are frequently engineers. To be successful you need to get it out of people’s brains and in to text. When the knowledge doesn’t live in someone’s head it means someone wrote it down but you may not know where it lives. This causes the next problem, organization.
Salesforce, in part, solves this by having an entire team dedicated to internal documentation. They handle the internal architecture, processes and knowledge sharing across the company. It’s a 7-10 person strong team. A lot of this is code documentation as Salesforce is a monolithic piece of code. Some of the other docs are around building out data centers, servers, and more.
Even if your company won’t ever create an internal documentation team there are things you can do. Leah gave some ideas for how you can start generating useful processes and tools. The first step is finding the people around your company who are like-minded people. Seek out those people who care about documentation and give them a forum in which to participate.
Leah’s found that engineers break down between three roughly equal groups. Those who are eager to help, those who are willing to help but need guidance, and those who are curmudgeons.
One thing Salesforce does to motivate engineers to write documentation is hold internal documentation hack days. They kick it off with a talk, set clear guidelines throughout the day, and set a fun theme (e.g. “Doc like a pirate day!”).
The number one thing with creating a culture of documentation is to understand that some text is greater than no text. You have to start somewhere and anything you can create is progress. You can fix the text later; the first step is to get it written down.
The curmudgeons in your company will argue that good code documents itself. As Leah put it, good code only tells what something does, not the intent behind it.