Sunday, September 27, 2009

Cleaning Up After The Doc Sprint

So, we had our doc sprint over the weekend, and I feel I should post my thoughts on the process.

Before anything else, allow me to say this: We had some amazing success.  After speaking with Chris Perkins, we had success beyond his wildest dreams. And I'm blown away by how well we did. So, even though the next couple paragraphs might sound like I'm down, I'm not.

Now, let me confess that this was my first ever sprint of any sort. Somehow, I was also (to some degree) the person that was supposed to lead the sprint. It felt kind of weird to have been entrusted with that, especially considering my relative newness to the project.

 As to how I did in filling that role, I'd only give myself a marginal passing grade. I feel like I didn't do enough preparatory organization, and didn't do enough maintaining of the actual focus on the task at hand. In my defense, I didn't really know what I needed to do to help make this doc sprint successful. I've learned, though, and will do better at these things next time.

My feelings over the whole sprint did quite a bit of up and down, as well. At some points, it felt like we had mired ourselves down, and were getting nothing done. At others, it felt like we were making amazing progress, and nothing could possibly slow us down. It's only now, after we've pretty well wrapped up, that I can see things a bit more clearly, and realize that we made amazing progress on this.

Before we started, on Friday afternoon, we had 192 items on our todo list, and they ranged from "define this term" to "write this whitepaper". So, we had a wide variety of items to do, and even wound up identifying previously unidentified items during the sprint. We're still closing out the sprint, but as of right now, we have 137 items on our todo list.

When you consider that we also found ourselves adding more todo items as the sprint progressed, we are certain that we closed out 55 todo items, and quite possibly we closed out 65 of them.

I don't care how you look at it, that's impressive. Nearly 1/3 of the original todo list was completed over the past two days. The people who participated in the sprint did a lot of work, and I'm proud of them. In alphabetical order (using hg log | sort), they are as follows:
  • Christoph Zwerschke / cito
  • Lee McFadden / splee
  • Mike C. Fletcher / mcfletch
  • Chris Perkins / percious
  • Sanjiv / sanjiv
  • Seth Davis / (seedifferently)
I'd also like to thank Jorge Vargas / elpargo. He did work on documenting custom content types, but in so doing he found an issue that needs to be resolved. Unfortunately, I'm not involved in the code side of TurboGears enough to really have understood, the issue, but it sounds like he's found something that will be of great help when he's cleaned it up.

I'd like to pay special attention to Mike Fletcher and Chris Perkins, though. Mike's work on cleaning up the tutorials improved them so much I can't begin to express it. And Chris's work on getting the middleware configuration documented so thoroughly is only going to make the 2.1 release of TurboGears that much better. Thanks go out to both of you for all your hard work this weekend.

Something else that might be of interest if you've read this far would be the stats on what we did. Well, here it goes: 86 commits, 51 files changed, 2568 insertions(+), 629 deletions(-). Think about that for a while, and remember that that's just the work from one weekend.

I'm still amazed, and likely will be for some time to come. This community really managed to come through, and clean up our documentation. It's a good feeling to see this happen.


seedifferently said...


Bravo! I'm sorry I couldn't hang out during the main push, but I got caught up on the IRC channel logger and was quite impressed with everyone's collaboration.

When things slow down a bit for me, I promise I'll be around more!

- Seth (seedifferently)

Chris Arndt said...

The great thing about open source is that you can learn by doing. I'm sure, the next doc spring will be even more productive thanks to your experience gathered by organizing this one.

Writing documentation is often not appreciated enough, IMHO, by your fellow project members or the community. But I actually find it often more intellectually challenging than writing code and a lot more laborious. So thank you very much for your efforts!


Mark said...

Sorry I was sick all weekend. You all did great work! And from the outside it sure looks like you did a great job of leading the sprint!

I'm going to try to do my own mini doc sprint sometime soon.

Thanks again for all the great work on the docs. You have no idea how grateful I am that work continues even when I'm not able to participate. The TurboGears community is filled with great people doing great work.

Chris Perkins said...

I want to thank you for all of your hard work to make this sprint possible. Your work and dedication to both review the documentation base, and collect all of the todo items really helped drive the sprint.

I think back to three years ago when this push was made: . I think we were an order of magnitude more successful than three years ago, primarily because of your organizational skills and attention to detail. I can't thank you enough; your work will enable TurboGears2 to meet one of it's primary goals, to have the best Documentation of any framework.