Documentation enchantments ideas

[rikl...@gmail.com]

I'm playing with django and pylons at once to see what I want and I
think I want pylons but the documentation is annoying (more examples
than explanation) and there isn't much of it. My ideas etc.:

- there is http://www.dreamprojections.com/SyntaxHighlighter/ which
highlights code. Use it in the documentation. It makes the code more
clearer. Currently quick_wiki is the most screwed up, and:
###########################
<div class="content">
SPACE_HERE% m.call_next()
<p class="footer">
###########################
After copy/paste from the browser. Not all know myghty at start...
- explicitly write from which file current code snippet is (where
should it go). Don't break code from one file - put all at once, then
explain parts.

- Make 2 types of docs: lesson, workshop... and other. Lesson describes
an element of Pylons, workshop uses knowledge from selected lessons to
do a working example with "home work" (make page A to show Hello
Earth, make a table and save current time). Quick-wiki would be a
workshop that would require learning from few (point which) lessons:

L - Forms: creating and getting the data
L - How to use SQLAlchemy with Pylons
W - Basic Wiki
L - How to use scriptaculous helpers
W - playing with scriptaculous in templates
W - Adding scriptaculous/ajax effect to the wiki

Write simple, then extend.

- No big mixed tutorials like current "Getting Started", should end
at "Hello World!" template, separate routes docs, "Controller
Variables and Template Globals", "Passing Variables to Templates"
also. Small and does what the Title/link says.
- more basic docs like "how to make a form and get the data in
controller", "how to use SQLAlchemy in Pylons", "how to
add/edit/delete/list/get" data from a DB using SQLAlchemy" (no
external links) (no quick-wiki, no scriptaculous), "Myghty
overview", "Routes how-to", "how to make links with url
helpers".:) totally basic one-thing-new tutorials
- external components like mythty, paste, routes.. get a overview
tutorial/s that explain common usage of them in pylons.
- few more simple apps workshops like the flickr search (I can write
one about web_search ;) )

[Martin]

Now that I've been playing around some more with pylons, I realize that
this "lesson"/"workshop"-idea would really be a good thing. I get the
impression, that there are some really useful functions in pylons, but
sometimes you just don't know, that this function exists(or how it
works). Especially for that kind of thing, small lessons like riklaunim
proposed would be nice.

Maybe we could collect suggestions for small lessons, and if people
like the idea, everybody can pick a lesson that he/she would like to
write... (and since it is just a small lesson, it is not that much work
to do).

Hmm... gonna extend the suggestions from above:

L - Forms: creating and getting the data

L - Validation: how to validate data from forms (using the
@validate-decorator)

L - How to use SQLAlchemy with Pylons
W - Basic Wiki

W - Basic Blog

L - How to use scriptaculous helpers

L - How to use webhelpers.pagination
L/W(?) - Advanced integration of SQLAlchemy (see thread:
http://groups.google.com/group/pylons-discuss/browse_thread/thread/f6ecf11c178b648b/215396b9ad1c1eb5#215396b9ad1c1eb5
Guess, this one would be interesting for lots of people.
Well...definitely for me)
L/W(?) - How to create command line scripts that can use your pylons
models... (see thread:
http://groups.google.com/group/pylons-discuss/browse_thread/thread/549fd90376728845/122b7cde28b7037d?lnk=gst&q=command+line&rnum=2#122b7cde28b7037d
)

W - playing with scriptaculous in templates
W - Adding scriptaculous/ajax effect to the wiki

So, any more ideas?

Cheers, Martin

[rikl...@gmail.com]

ideas will show up :) just think what "workshop" examples you want to
make...

I can write few docs. I've "extracted" SQLAlchemy + Pylons from quick
wiki and I can write about it I think :)