I've been thinking about the best mechanism to beef up examples, today we have two different places I am putting code examples:
docCookbook: this a real doc page you can hyperlink and navigate using HTML navigation
"examples": directory with real Fan scripts you can run/tweak
I'm kind of thinking the example approach is more useful because you can actually run them, tweak them without copying/pasting code.
But today, examples don't cleanly fit into the documentation today. But if we actually included doc navigation for example code I think we could solve that problem.
So I guess my question is - do you guys like getting rid of docCookbook in favor of just example scripts for all the topics?
eeeSat 15 Aug 2009
the examples have been more useful to me, especially the web ones. since everything has to be a class (is that right?), you have to show the class every time, IMHO. Otherwise, a newbie is missing context.
If you are talking about putting the examples online and having them filled with hyperlinks to baseclasses and docs ... that was my next comment. It's not convenient to HAVE to browse to the examples directory in source code. What's the incentive to even do a download if the examples don't look cool?
yeah, I was thinking about this. glad you brought it up.
andySat 15 Aug 2009
Seems like most of whats in cookbook now can go directly into the fandoc for each slot (and probably more useful there anyways). And then, as eee notes, we should focus on the examples for the bigger picture, and how things fit together and tick, etc, etc. Those files should definitely be online as HTML in either case.
brian Sat 15 Aug 2009
I've been thinking about the best mechanism to beef up examples, today we have two different places I am putting code examples:
I'm kind of thinking the example approach is more useful because you can actually run them, tweak them without copying/pasting code.
But today, examples don't cleanly fit into the documentation today. But if we actually included doc navigation for example code I think we could solve that problem.
So I guess my question is - do you guys like getting rid of docCookbook in favor of just example scripts for all the topics?
eee Sat 15 Aug 2009
the examples have been more useful to me, especially the web ones. since everything has to be a class (is that right?), you have to show the class every time, IMHO. Otherwise, a newbie is missing context.
If you are talking about putting the examples online and having them filled with hyperlinks to baseclasses and docs ... that was my next comment. It's not convenient to HAVE to browse to the examples directory in source code. What's the incentive to even do a download if the examples don't look cool?
yeah, I was thinking about this. glad you brought it up.
andy Sat 15 Aug 2009
Seems like most of whats in cookbook now can go directly into the fandoc for each slot (and probably more useful there anyways). And then, as eee notes, we should focus on the examples for the bigger picture, and how things fit together and tick, etc, etc. Those files should definitely be online as HTML in either case.
brian Sat 15 Aug 2009
Promoted to ticket #721 and assigned to brian
brian Tue 8 Sep 2009
Ticket resolved in 1.0.46