The people who use out-of-the-box weblog themes fall into a number of different categories. There are developers who take themes apart to learn new tricks; there are those who have the technical skills to make their own, but not the time; and there are content producers, people who want a blog but can’t design it themselves and can’t (or don’t want to) pay someone else to do it.

Of these groups, the first two are the most likely to want documentation: how things work, what to change if you want to tweak something, and so on. The last group doesn’t want documentation: they want it to work. Customisation is a nice bonus, but really what they want is to throw up a blog and get on with it.

As a student of the teach yourself school, at least when it comes to web development, I reckon developers can tweak weblog themes (which tend not to be that complex) without much in the way of documentation. A few brief pointers could be worth jotting down, and obviously code needs to be commented to some extent, but in the end if they want to take it apart and put it back together again, they can do it well enough without the original developer investing too much time in documenting the theme.

What’s really important is to make sure that it works out of the box. Moreover, any theme which gets into widespread circulation will inevitably become tired after the hundredth website using it. Some way to customise it, without needing to get into the guts of it, is immensely valuable, whether it’s tweaking the layout, adding content, or changing the header. Things like this are optional extras, yes, but they give major additional value. Sometimes they may have to wait for later revisions—try to do everything in the first release and in all likelihood it will never be finished—but helping users to differentiate their site from others using that same theme is not something to be ignored.

A brief conclusion: don’t write too much documentation, just make things work. Anyone who wants to make major changes should be able to figure it out easily enough, as long as your code is well-organised with occasional helpful comments.