Compound Thinking

The State of TurboGears Documentation

Recently there has been quite a bit of lively discussion about the current state of the online TurboGears documentation on the mailing list. And it’s pretty clear that our users are telling us that we need to improve the docs, and I want to assure people that this is a message we’ve heard loud and clear, and I agree that it is a message we really need to hear clearly.

The good news, is that it’s not a new message. We know that writing good documentation is one of the most important tasks for developing a project like TurboGears, which brings together lots of existing Python libraries into a single “framework.” And we’re working hard on building the best documentation we can. In fact we’ve already planned a DocSprint for this weekend.

There’s definitely a gap between where we are, and where we should be.

So, I thought I’d write up a bit of perspective about how we got here, how we’re doing right now, and where I think we need to focus our efforts in the short term. In another post I’ll talk about our long term goals.

How did we get here?

As of last PyCon, we planned to migrate all of our documentation work to Docudo, and some time was spent waiting for that project to get ready for prime time rather than writing docs, since we didn’t really have system in place yet. Eventually we found out that Docudo was going to take longer than we had, and found a way to make MoinMoin do most of what we needed, and we transitioned to that.

All that waiting, and the complexities of migrating docs from the Trac to the Wiki slowed our momentum, which was trouble since we were already behind.

How are we doing now?

Given the delays we had, there’s been a surprisingly large amount of work put into the Docs. But there are a couple of issues with some of that documentaiotn. Some of it is written against old versions of TurboGears and needs to be tested against 1.0. And other docs were written up quickly by a user, and need a little love and care before they can become official.

But really, there are a lot of good docs out there. They just need organizing, cleanup and someone to fill in the gaps.

We can’t get back the months that we lost, but we’re definitely moving in the right direction.

According to a rough count I did the other day, I think there are over 250 edits to the Docs in the last month. Which indicates that we are doing better.

You could even say we’re catching up! But as always, we have some way to go, and we could certainly use more help.

What do we still need to do?

I’d like to focus our efforts over the next week or two on four areas:

1. Widget Documentation
2. Overview Documentation
3. Generated API Documentation
4. Widget Browser updates

Widgets are still not thoroughly documented, but we’ve come a long way in improving the docs over the last month. There are a number of widget docs in RoughDocs awaiting review, cleanup, and promotion to the official docs.

And we still need a couple of good Overview docs, one for the beginner, and another for people wanting to get involved in development on the TurboGears core.

Jorge Vargas has started the process of getting epydoc generated API documentation ready for the site. Now we just need to get that posted to the website, get a few remaining glitches worked out of the widget API generation, and make generating a new set of API docs part of the release process.

Once we have API generation going well, I’m pretty sure that it will tell us that need to start improving the docstrings in the code in some places.

If we can get these things done, we’ll be in a lot better shape than we are now.

Of course there’s more to do in the longer term.

For example, it would be great to have really comprehensive tutorials for SQLObject and Mochikit. And we could use a lot more Diagrams, and better Documentation for developers who want to get started hacking on TurboGears itself.

And of course, we need to keep our eye on the TurboGears 1.1 development process.

So there’s lots to do, but we have a team of people who are committed to making all of this happen. But it will definitely happen faster if we have help.

There are tasks like verifying that documentation code that was written 8 months ago, still works on TurboGears 1.0, that anybody can do, and that provide a good way to learn more about TurboGears. And we have some docs to convert in to the new reST wiki format.