Documentation Driven Development and Corporate Tool

At  PyCon 2011, I attended a talk by Corey Oordt titled " Documentation Driven Development". I really enjoyed it. It focused on writing your documentation before coding and then coding to your documentation. In some ways, this is the same as what is taught in school: "Do a  requirements analysis, produce a  software requirements specification, and write a  scope statement. Then code". However, that's selling documentation driven development short.

The main problem with overly formalized scope statements and requirements documents is just that: they are rigid and definitely not agile¹. I have never seen an open source project that operates in that way. Overly formalized and rigid processes are one sure way to scare off contributors and slow development to a crawl. In the 21st century, it's all about about being "agile". To paraphrase a certain exuberant CEO: Iterations, iterations, iterations! In the open source world, this is known as "release early, release often²".

Not surprisingly, developers like to code. Most don't like to document. Personally, I have no love of writing³. However, documentation is of utmost importance. Especially to open source projects.

Again, developers like to code. I don't know any who love to read other people's code. If I am looking for a project or tool, and I come across one with documentation and one without, I'm always going to chose the one with documentation. In the end, I may end up needing to read the code of the documented project. If I do, however, I will have an understanding of how the project works. This gives me a much better chance of easily understanding the code. Using an undocumented project is a guarantee that I'll have to wade through code and try to figure out what the developer was thinking. Documentation not only helps newcomers to the code, it also helps the original author. I guarantee that every developer has code which they wrote, didn't document, revisited in 6 months to a year, and cursed themselves for not documenting it. I'm definitely guilty. However, on projects with a development team of one, documentation instantly seems less important. It can also feel like a hinderance to the "release early, release often" ideal⁴.

Most open source projects start out as a one person development team. This makes documentation all the more important. Any documentation will help attract contributors and good documentation can help bring users. This is why documentation driven development is a great idea. Instead of documentation being an afterthought, it is an integral part of the development process. Documenting before developing can also help in thinking out a problem. Like test driven development, one writes the end goal first, then the implementation. This assists in knowing when the end goal has been reached.

The key with documentation driven development, and where it differs from the more rigid requirements analysis, is that it must be an iterative process. The point isn't to finish all of the documentation and then write all of the code. The goal is to write documentation so one knows what to code, and then update the documentation while coding. At the end of the project, one has a system that is documented, and should be thought through⁵.

Enter  Corporate Tool. I have been using  Trac at work for "issue management" for about 6 years now. All the way back to the 0.8.4 days. It is a good project. It's hosting this blog, even though it's really a ticketing / source control management system. However, it is just not working for me anymore⁶. I could continue to write plugins for it, however, I don't think this would adequately solve the problem.

I've been thinking of what I want from a ticketing / issue tracking / task list / wonderflonium system. I have many ideas floating around my head on how I'd like to architect it and what technology to use. I have struggled, however, with where to start. On Friday I started documenting some of my thoughts. On Saturday I attended Corey's talk. I am pressing forward and have decided to pursue my ideas. I don't have any code yet, but I have started on the documentation. I have created a  Corporate Tool project on github. The documentation can be found on  Read the Docs.

I will be working on Corporate Tool during the  PyCon sprints. Please contact me if you're interested in documentation driven development or corporate tool.