Posted in 2016
Questions after talks at conferences
- Nov 12 2016
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.
Semantic Meaning in Authoring Documentation
- Oct 06 2016
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.
A Selfish Appeal for Documentation
- Sep 24 2016
Writing code is the act of building a mental model of a problem, and then translating that model into executable software.
Funding Open Source with Marketing Money
- Aug 31 2016
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.
The Power of Sphinx: Integrating Jinja with RST
- Jul 25 2016
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.
An introduction to Sphinx and Read the Docs for Technical Writers
- Jul 01 2016
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.
Why You Shouldn’t Use “Markdown” for Documentation
- Mar 15 2016
“Markdown” is the most commonly used lightweight markup language on the internet. It is great for a subset of tasks, mainly blog posts and commenting. However, lately it has been adopted by the technical writing community as a solution for writing documentation.
