Write the Docs: A plea to Open Source Maintainers

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

More technical writers need to contribute to Open Source documentation. There are recurring patterns of discouragement when writers try to get involved. Writers hear things like, “The source is self-documenting.” Or, “Oh, that code’s being rewritten.”

The single most common thing is just silence. That doesn’t help anyone.

Documentation can always be better, it’s never perfect. Open Source developers have other priorities than docs, that’s okay. Turning away English majors, though, misses an important opportunity. We can start a virtuous cycle where writers are involved and, thus, bring more writers to a project.

At a basic level, talk to a writer. Figure out how best you can work together. You can also organize a docs sprint. It’s a great way to start and accomplish a lot specifically with docs. On a more advanced level, you can mentor a writer. Be the veteran who can help introduce a writer to your Open Source project of choice.

Perhaps in the future we’ll have better living through documentation. It’d be cool to see a Summer of Docs at some point in the future.