I’m a bit late in the game regarding blogging about the GNOME Developer Documentation and Tools Hackfest that we hosted at the Openismus Berlin office a couple weeks ago. There have been a number of good posts made summarizing what we talked about and worked on. In this post, rather than providing another summary, I’d like to share my thoughts about how we can get the most out of the demos (examples, tutorials… whatever) we started during the hackfest. Some of what I’m going to talk about was discussed at the hackfest, but much was not. Also, be warned that this will have quite a few references to Qt documentation practices.
A Tutorial for Tutorials?
So here we are, we’ve got some nice, simple code examples, some even with tutorial-style documentation. But if you look through the examples you’ll find that the documentation style varies dramatically. Before we go and write too many of these tutorials maybe we need to standardize how we write these. Some issues that arise when writing the tutorials are:
- how do we structure the tutorial? Daniel’s Magic Mirror example incrementally builds up the program while others, including mine, explain the finished program.
- how does one reference the code? Do we use line numbers, show full functions/classes? Do we include unexplained code in the code snippets?
- how do you show a full listing? Do we append a full code listing at the bottom of the tutorial or provide links to files?
- how much should we comment the code? If the code is going to be explained, do we need to repeat the same thing in the code comments?
- and so on…
Some of these have answers. For example, we decided that we should build up the programs incrementally and that referencing line numbers is probably going to be more trouble than it’s worth.
When I was writing my photo-wall tutorial I knew that I was writing it not in isolation but as a larger collection. Thus, I wanted my tutorial to fit in with the other tutorials in the collection. As there was no guide to go by, I poked around the repository to see how others were doing it. I found one I liked and went with it.
The point is that because there is no canonical tutorial or document to go by, we are adding a possible barrier to those wishing to create such tutorials. During the hackfest it was mentioned that we can not motivate people to contribute, we can only demotivate them. Let’s not do that.
For completeness these are my opinions about the above-listed issues.
- structuring the tutorial: Incremental build up is nice for GNOME beginners and that seems to be the target group so let’s go with that.
- referencing the code: No line number referencing. Break the code up into small logical blocks and describe. Blocks need to be small so that one can read the description and see the code without having to scroll up and down repeatedly.
- showing a full listing: Do like the Qt examples do; list all files at the beginning of the tutorial. This gives quick access to folks who don’t need the description.
- commenting the code: Heavily comment the code so that is descriptive outside the context of the tutorial and probably remove the comments when placing segments in the tutorial in order to save space.
Dealing with undocumented code examples
Right now I don’t know that we have a plan for dealing with this so here are my thoughts.
In a perfect world we are going to have a tutorial written for each example in each of the core programming languages. As perfection is rather boring, lets think about the alternatives.
I think in this case we should simply look at the Qt examples. They either have a tutorial-like description or they don’t. The one’s that do have an asterisks, those without don’t.
Regardless of whether the coder is willing or able to write an accompanying tutorial, we should promote getting as many code examples in as many core languages. In fact some example may be too large to expect a tutorial. Take a look at the Qt Network torrent example for one instance of this being the case. Looking at that example you’ll see that even though there is no tutorial, a file listing and description is available. If we were to standardize on having a file listing and functional description of the example at the top of each tutorial we could just copy the description and list the files for each newly added example port. Of course, hopefully someone would eventually get around to writing a tutorial as well.
Relating reference documentation with examples
One of the nice things about the Qt reference documentation is that it often references examples in the See also section. With one click your sent to an example that’s probably more complete than the small snippets you usually find in the API reference. Looking at the QTcpSocket class you’ll find 6 referenced examples. Some have documentation while some are just commented code. Maybe Shaun has something up his sleeve for something like this using Mallard.
Basically, I would like to see a consistent, wide-ranging, integrated and ever growing set of examples and tutorials to help developers get started with developing with GNOME technologies. I think the Hackfest was a great start to getting us there. The documentation team has done a great job laying the foundations and providing infrastructure for getting us where we want to be with GNOME 3 regarding developer docs. We just need to finish ironing out a few things before we are quite there.