Kurt McKee

lessons learned in production


Hey there! This article was written in 2009.

It might not have aged well for any number of reasons, so keep that in mind when reading (or clicking outgoing links!).

Writing documentation

Posted 10 August 2009 in listparser

I know that one of the most challenging things about writing software is writing documentation. Usually this is chalked up to "programmers prefer to program" and "writing documentation isn't glamorous" and so forth, but as I rely on high-quality documentation, I want to provide others with the same.

To that end, I'm in the process of writing just such documentation for listparser. Surprisingly, as precise as I think that I've been while writing it, codifying listparser's behavior is revealing that it has a few inconsistencies. As an example, the OPML version is supposed to be a string (either an empty string or one of opml, opml1, or opml2); under at least one circumstance, however, the version may be reported as None. In each case, I'm making a mental note to go back and amend the behavior.

Since I'm moving next weekend and still looking for a job, none of the above is a high priority, but watch for a release in relatively short order.