Auto-building Sphinx docs May 24th, 2012
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'
Writing Great Documentation: You need an editor November 12th, 2009
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.…
Writing Great Documentation: Technical style November 11th, 2009
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.…
Writing Great Documentation: What to write November 10th, 2009
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:…
Dojo gets a manual December 23rd, 2005
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.