Tag: Documentation

Auto-building Sphinx docs

Here’s a quick way to automatically regenerate your Sphinx docs as you make changes to the source. There’s probably a million ways to do this; here’s mine:

$ pip install watchdog
$ watchmedo shell-command \
              --patterns="*.txt" \
              --ignore-pattern='_build/*' \
              --recursive \
              --command='make html'

May 24th, 2012 • documentation python sphinx tips

Writing Great Documentation: You need an editor

I’m supposed to be this expert on writing, right? So how come my previous articles have had so many errors?

Simple: my blog doesn’t have an editor.

That’s typical for a blog, but it’s unfortunately also typical of open source documentation: the vast majority of technical documentation doesn’t reach far beyond rough draft status.

All good writers have a dirty little secret: they’re not really that good at writing. Their editors just make it seem that way. It doesn’t matter how well you’ve mastered the language; nobody, even grammar geeks, gets this stuff right on the first pass.

November 12th, 2009 • documentation editing editors writing

Writing Great Documentation: Technical style

Now that I’ve discussed what kinds of technical documentation to write, I can move on to the question of how to actually develop a writing style that produces great technical documentation.

Learn to write

Unfortunately, there aren’t any shortcuts here. The best way to learn how to write great documentation is to first learn how to write (anything). There are some important differences between technical documentation and your average prose, but a solid foundation of good written communication skills is an irreplaceable prerequisite.

November 11th, 2009 • documentation style writing

Writing Great Documentation: What to write

Tech docs can take a bunch of different forms ranging from high-level overviews, to step-by-step walkthroughs, to auto-generated API documentation. Unfortunately, no single format works for all users; there’s huge differences in the way that people learn, so a well-documented project needs to provide many different forms of documentation.

At a high level, you can break down the different types of documentation you need to provide into three different formats:

November 10th, 2009 • documentation writing

Dojo gets a manual

Since my last post hit the Dojo folks pretty hard for the lack of documenation, I’d be remiss if I didn’t point out that they now have a manual online.

It’s far from complete at this point, but it covers most of the basics and it’s been really enjoyable to read through. I’d certainly say that huzzahs are in order.

December 23rd, 2005 • documentation dojo