The post I never published
Looking back, the file was created on my 29th birthday:
How software gets explained: Read the Docs, Write the Docs, Sphinx, and the craft of docs.
Looking back, the file was created on my 29th birthday:
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 documentation is the separation of what something is from what it looks like. What we mean and what we display are very different things.
Writing code is the act of building a mental model of a problem, and then translating that model into executable software.
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.
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.
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.
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.
I helped create Read the Docs over four years ago. It started with a humble goal of replacing a cron job on my own server. Since then, it has grown more than I ever could have imagined. It has become vital infrastructure for the Python community, and the programming world in general.
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.
As a developer, you develop instincts for judging quality of code. One of my favorite interview questions is:
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.
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.
We have been hard at work improving Read the Docs over the past month. A large amount of back end work has been going on, and now we have a brand new documentation theme to showcase it.
Or how I learned to stop worrying and write a book.
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.
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.
A few days ago I started a campaign to improve documentation. Today I have the first results to show from this work.
tl;dr: I don’t have (or want) a job, help fund me to make the documentation world better.
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.
As the maintainer of Read the Docs, I spend a lot of time looking through random projects, and getting inspired. People have been doing lots of interesting things with the project, and I’d like to highlight some of them.
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.
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.
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.
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.
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.
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.