Chris Kühl makes some good points about choosing style and structure in the developer docs that we've been working on recently. He answers his own questions in his post, but I thought I'd elaborate on them:
How do we structure the tutorial? Daniel’s Magic Mirror example incrementally builds up the program while others, including mine, explain the finished program.
Incrementally building-up the example is the best idea, I think. This allows you to present the material in a logical order, building-up concepts as you go. The structure of the code doesn't necessarily mirror the order of the steps you would take to write it, for instance. You should have the full, finished code in a linked-off file anyway, so the reader hopefully won't get completely lost when you start changing around blocks of code. Keeping related concepts together and then building them up allows the reader to concentrate on understanding one thing as a coherent set of ideas before moving onto the next set of concepts. Try to match the tutorial's structure to the way the reader will need to think about the code rather than how the code is laid-out in the source file.How does one reference the code? Do we use line numbers, show full functions/classes? Do we include unexplained code in the code snippets?
Line numbers are a bad idea because they're difficult to maintain (code changes!) and they force you to refer back to the code listing. If you include the actual line (or part of the line) of code that you're referring to inline, the reader can see it right there and doesn't need to waste time trying to find it again in the code listing to remind themselves what it's for. Normally, simply referring to the function being called is sufficient for the reader to be able to understand what you're talking about.A small amount of unexplained code is fine, as long as it's obvious what it does. If you have several lines that don't need explaining, break up the snippet into two bits that surround that unexplained block. That way, you're focusing on the important material and not distracting the reader.
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?
I recommend linking to a file - that way, you can just copy and paste the whole file and compile it, without having to muck around with a text editor. It also makes the guide shorter and less daunting. Plus, it's easier to maintain separate code files because you can test/compile them directly.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?
Don't comment the code in the code listings inside the tutorial. It's distracting: the point of the tutorial is that you're explaining the bits of code that need explanatory comments! If it's expedient, short comments can be used to skim over unimportant points if you really need to (e.g. "This exits the app"), but anything more gets in the way of the code. Of course, the separate source code file you provide should be well-commented, but not to the extent that the comments make it difficult to follow the code.Realising the educational promise of open source code
Chris also brings up undocumented code examples. He thinks that "we should promote getting as many code examples in as many core languages" as possible. This is really sensible - inspecting an example which is known to work is a good (and well-used) way of getting to grips with a technology, and writing example code takes much less effort than writing a tutorial. It's nowhere near as good as a tutorial for people lacking a conceptual understanding of what you're doing, but a moderate sprinkling of comments and relative simplicity of the example is normally enough to get people some working code.
But, being an open source project, we can offer something of a similar value without even having to go to the effort of writing new examples. All of our code is open and free to view in git, so why not link to examples in existing projects? This has the advantage of showing the code working "in the real world", displaying it in context, with all of its supporting infrastructure. Sure, links can get broken, and real-world examples aren't as clean as purpose-made ones, but I do think it's something we should pursue. Maybe a "Real-World Examples" section on developer.gnome.org would do the trick? Would this be useful to you?
real world examples
Stefan Kost
pull snippets from working programs
The tricky issue is how you indicate what part of the original source code belongs in the snippet. Doing it by line numbers will drift out of sync:
{{snippet original=gtk_tutorial/helloworld.c lines=17-24}}
Doing it by naming syntactic elements in the original source code makes it hard to excerpt arbitrary lines:
{{snippet original=gtk_tutorial/helloworld.c show=function(delete_event)}}
It seems the best way is to surround the snippet in the source code itself with comment markers, something like and then in the documentation just refer to that name
{{snippet original=gtk_tutorial/helloworld.c use=delete_handler}}
Some programmers will object that this clutters up their code, but the comment markers let programmers know that this piece of the file appears in documentation.
Some of the ad hoc "Interactively learn HTML5!" tutorials come close to this ideal, although they have the advantage of presenting-editing-running their code samples entirely within the web page of documentation. DocBook implements snippet interpolation using
xi:includeand a separate program that extracts named snippets from source files ( http://www.devx.com/java/Article/35301/0/page/4 ), I've never tried to get it to do syntax coloring.