Posted in 2016

Questions after talks at conferences

At many conferences, people allow the audience to ask questions after the talks. I want to argue that this is an anti-pattern in many ways, and some solutions that have worked that I recommend.

Read more ...


Semantic Meaning in Authoring Documentation

Semantic Meaning in documentation is the separation of what something is from what it looks like. What we mean and what we display are very different things.

Read more ...


A Selfish Appeal for Documentation

Writing code is the act of building a mental model of a problem, and then translating that model into executable software.

Read more ...


Funding Open Source with Marketing Money

Often times as developers we see funding open source as a charity. We will give our personal money to projects we believe in. If we’re lucky, our company might have a matching program for our donations. This has proven not to be a sustainable way to support open source.

Read more ...


The Power of Sphinx: Integrating Jinja with RST

Sphinx is a super powerful tool. This has its upsides and downsides. One of the major downsides is that historically it has been built as a framework that allows users to do just about anything. This is great, except it also means that a lot of the specific value out of the modular design hasn’t been documented or made explicit to users. I’m hoping to address some of this power in a set of blog posts.

Read more ...


An introduction to Sphinx and Read the Docs for Technical Writers

Treating documentation as code is becoming a major theme in the software industry. This is coming from both sides, with developers starting to treat documentation as a priority alongside tests and code, and writers seeing a lot of value in integrating more into the development process. This marrying of cultures isn’t simple, but having the proper tools for the job makes both sides happy with the process and the results that get produced.

Read more ...


Why You Shouldn’t Use “Markdown” for Documentation

  • Mar 15 2016

This post was written in 2016, and the landscape here has changed. I still mostly agree with what is important, but the “Markdown” ecosystem has evolved and gotten other capabilities that might change the calculus of what is the right tool for your organization.

Read more ...




Hey there! I'm Eric and I work on communities in the world of software documentation. Feel free to email me if you have comments on this post!