Words by c.z.robertson

Improving code through documentation

2002-09-22 17:39:29 UTC

After a week in which I barely touched any code at all, I've just had a bit of time in which to work on Catkin and I'm getting closer to releasing 0.2.

I've just been working on a bit of documentation. In particular, I've been documenting the template system. Doing so has taught me a bit more about what's wrong with my code.

The most striking thing is that my terminology is a bit screwed-up. Throughout the code, and leaking into the templates, the blog entries are referred to as "stories", yet in the documententation I want to refer to them as "blog entries". (I'm assuming familiarity with the concept of a blog.) "Stories" just doesn't sound right.

This gives me a dilemma: do I fix this problem before releasing 0.2, or does the principle of "release early, release often" compel me to release 0.2 and then break the template format again in a future release? Making the changes won't be hard, but I'm still leaning toward the latter. I'm sure that the template format will have to be changed sometime in the future anyway, so I'll just put this change in the queue and try to make a bunch of changes in one go.