excess.org

Ian Ward

Software
CKAN contributor/tech lead
Urwid author
PyRF contributor
Speedometer author

Presentations
Contributing to Open Source
IASA E-Summit, 2014-05-16
Urwid Applications
2012-11-14
Urwid Intro
2012-01-22
Unfortunate Python
2011-12-19
Django 1.1
2009-05-16

Writing
Moving to Python 3
2011-02-17
Article Tags

Home

Ian Ward's email:
first name at this domain

wardi on OFTC, freenode and github

Locations of visitors to this page

Write the Docs

Write the Docs
Posted on 2013-04-06, last modified 2013-10-14.

I've spent a lot of time with Sphinx this past year working on updating and improving the Urwid documentation. I've found writing documentation is a really hard but also really important and rewarding part of my programming work.

update 2013-10-14: videos posted here

Notable talks: Integrating Development, Documentation and Reporting, Getting Developers and Engineers to Write the Docs, How Mozilla supports users all over the world, Typography for Docs, Write Tight(er)

At this conference I learned lots of things I'm doing wrong. Dark borders on my urwid docs detract from the most important thing: the content. I should be limiting the number of characters per line.

I liked the suggestion that a FAQ is a list of bugs. If people really are asking these questions all the time, why not fix the software?

I also learned a lot about writing in general, and had lots of fun. I couldn't get used to some people saying just "doc" (without the s) for documentation, however.

Tags: Software