Freitag, 5. April 2013

OSS documentation: Thoughts about the Symfony Docs Hack Day

Last Saturday was Symfony Docs Hack Day, and I think it was very successfull. Both WouterJ and weaverryan worked hard to provide information to everyone in need and were well prepared. The workflow was very nice, the Google Docs document was exactly the information everyone needed. Many issues got attention, many PRs got created and there are already some which are merged. The attitude was supportive, the chats really nice. Everyone cheered about PRs and had a good time (at least as far as I can say).

If you want some statistics about the Hack Day or want to see a list of pull requests and contributors, head over to the symfony blog. I'll focus on what this Hack Day really means for the framework and the community.

Normally, hackdays happen to improve the code. And that's ok and a good way to work on a project. But the documentation is nearly as important as the code. Without good documentation, the best framework or library will be unusable. There are many projects out there which might be awesome but due to the lack of documentation are never adopted. Developers might try it once, but as they don't understand how it works, abandon it pretty soon.

The symfony docs always have been a very good source to understand the framework. symfony 1 had a nice "jobeet tutorial", telling the internals by creating an example project in 24 days. symfony 2 started with a good documentation called "book" and advanced cookbooks. symfony always took care that the docs are up-to-date and worked on making the docs nice to look at. Due to this effort, there are now many people caring about the documentation in much the same way as others care about the code.

I believe this attitude has built an environment in which people work hard to do a hackday on the documentation. It's an environment in which many people join this hackday to make the documentation better. It's an environment which will make the framework itself better.

Creating such and environment is pretty hard. If you don't think of docs as one of your core features, you will most likely fail. If you "just write something so people can use it", there won't be many people to make it nice. The initial effort is big, and if you look at symfony, I guess they learned a lot from the first version. You also need the people who developed to write some of the initial doc. Looking at the Contributors Graph you can see that Fabien did most of the initial work. Others took over so he could focus on managing (or coding, I don't know), but in the beginning much of the docs were written by him.

And if you want people to contribute, it must be easy. Sphinx, the docs framework used by symfony, is not the easiest but it does the job. But if installed correctly, you can create the docs with one command and have a look at the plain html. The layout is different, but the features are there and you can check if anything is broken. Making it difficult to create the html locally means making it difficult to make good pull requests. Some guidelines also help.

All this combined has lead to a awesome documentation, both for beginners and advanced users. It's a joy to read and most likely helps with all issues at hand. Thanks to fabpot, weaverryan, WouterJ, stof and all the other who contributed, both on the hackday and in the past!