Documentation

How software gets explained: Read the Docs, Write the Docs, Sphinx, and the craft of docs.

27 posts

Documentation is JSON for the Brain

When you are writing software, you build a mental model of the program in your brain. This is how you make decisions and reason about how the program might work, how data flows, or what designs make the most sense.

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.

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.

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.

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.

Why You Shouldn’t Use “Markdown” for Documentation

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.

Why I’m building a company: Structure

There are a lot of reasons to build a new company. A large part of it is wanting something to exist in the world. However, there are ways to manifest things that don’t require a new company.

Read the Docs goes full-time

We have some exciting news in Read the Docs land this week. The project has been accepted into the Portland Incubator Experiment, as an open source project. This means that we have office space provided to us in Portland for three months, where we will be working on Read the Docs full-time. There will be two of us working on this: Eric Holscher and Anthony Johnson.

Sphinx isn’t just for Python

I have heard a few times over the past couple months that Sphinx is “mainly for Python projects”. This line of thinking makes sense, because Sphinx was created to document Python itself. Sphinx however, is a generic documentation tool that is capable of documenting any software project.

Read the Docs 2013 Stats

2013 has been a big year for Read the Docs. Our mission is to make documentation hosting easier, with the overall goal of increasing the quality of documentation in the programming world. I believe that we have been doing good work towards that goal, and I want to share some numbers to reflect our progress.

Announcing Grok the Docs

I’ve asked myself these questions a lot. Historically I have put Google Analytics on my doc pages, and called it good. I would browse over the data every once in a while, gleaning basically zero information out of it.

Sphinx Live Preview

For a long time, there has been a live preview site for reStructuredText: http://rst.ninjs.org/. It is really fantastic for learning the language. The immediate feedback is really valuable in helping you expirment and see how things work.

Announcing Write the Docs

Documentation is one of the most important parts of a software project. However, a lot of projects have little or no documentation to help their (potential) users use the software. A few years ago we started Read the Docs to help make hosting documentation easier. Part of the reason was that if hosting documentation was a solved problem, it would make people more likely to write docs.

Help fund Read the Docs

Currently Read the Docs is funded mainly through Corporate sponsorship. The Django and Python Software Foundations (non-profits), Mozilla, Lab305, Revsys, and others have helped keep the site running. However, this requires finding sponsors to help donate to the site every 6 months or so to keep things running.

Why Read the Docs matters

Documenting projects is hard, hosting them shouldn’t be. Read the Docs was created to make hosting documentation simple. I think that we have solved this problem well, but now we need to start thinking about the larger picture.

Read the Docs Update

It’s been a while since I last talked about Read the Docs, and there has been a lot of activity. This is an update on the latest and greatest new features.

Read the Docs Updates

Documentation writing will always be hard work. It’s a much different mind-set than programming, and people that write good code might not necessarily write good docs. However, this is a known issue, and something that can’t really be solved.

New features on Read The Docs

Since the Django Dash ended, We’ve been working on adding some requested new features to Read The Docs. There are a couple of major ones that we have added that I’d like to talk about.

Announcing Read The Docs

This year’s Django Dash just came to an end, and I’m really excited about the project that we built. I’m sure the other teams are feeling just as stoked, because there is an amazing amount of awesome work that was done in the last 48 hours.