On 11/02/2012 12:10 PM, kusut wrote:
On 1 November 2012 07:22, Chris McDonough <[email protected]> wrote:
Bring on the bikeshed,
Hello. You asked for the bikeshed?
The idea here is to ease beginners into pyramid, so this is kind of
unrelated to the docs overhaul tickets on github. Sorry. To make it
more accessible to beginners, we need to create an entry point
(getting started) docs. My take on this is to separate this starter
docs from the current docs (which is already a good narrative
reference).
I general I agree with this.
Why the separation? Because both docs are different in nature. I also
had a good experience with djangobook.com which did a good job
hand-holding me, and it's not a part of django docs. So in the end, we
will have two docs, a starter one and a (narrative) reference one.
Maybe we can combine the starter docs with the current docs? That is
up to you. I'll refer them in this email as separate entities.
Starter Docs Ideas
- The point is, after reading through this docs, users wont feel
intimidated reading current docs
- Few examples to steal from: http://flask.pocoo.org/docs/quickstart
and djangobook.com
- At the end of every chapter, put reference links (more info/details,
examples, you might be interested in.. etc). These links point to
later chapters, current docs, cookbooks, or external sites (raydeo
auth, pyramid-blogr, etc).
- Move "Installing Pyramid", "Creating Your First Pyramid Application"
and "Creating a Pyramid Project" content here (of course with changes)
- Explain "Application Configuration" and "Startup" as simple as
possible. Maybe?
- Explain difference with PHP (long running process etc)?
Current Docs Ideas
- Simpler English
With this suggestion, hopefully there wont be much changes in our
current docs (re-ordering chapters wont be necessary, right? so some
docs tickets can be closed) since it will serve as our narrative
reference. The dumbing-down will happen in the starter docs. If there
is any need for beginner topic, let's say 'templating', we'll keep
templating chapter in current docs as it is, and write the newbie
version for starter docs.
Here is what I have in mind for starter docs layout (and contents);
1. Some forewords? long running process etc? wsgi? web server? how
python webdev in general
2. Installation, virtualenv, and packaging.
Pip, easy_install, pypi, etc. Things to consider: system python or
not? Can we point them to another docs when it comes to installing
python for their system?
3. One-file project.
Explain every line. "Creating Your First Pyramid Application" did
pretty well on this. Do NOT mention TCP, HTTP (if possible), logging,
and wsgi (unless wsgi is mentioned beforehand).
Explain Configurator and make_wsgi_app as plain as possible. Do not
mention registry. Also teach readers to get GET/POST parameters here.
Things to consider: add_view vs view_config. Maybe strictly use
add_view here?
4. Multiple files project without using scaffold.
Teach readers how to build a multiple-files project (within python
package and/or not?) without using scaffold (expanding the previous
one file app). Teach them about renderer and template here? If
possible, teach them ini files, pserve and waitress here. If not (too
complicated without scaffold/entry-points), save it for the next
chapter).
view_config + config.scan here? or wait until we use scaffolds?
This chapter will give them some python basic knowledge (packages,
modules, __init__ file etc). To spice it up, multiple template files
(and teach them about asset specification syntax) and changing
templating engine (built-ins only, mako and chameleon, with link to
pyramid_jinja at the end of the chapter). If this is too crowded,
split this to another chapter.
5. Creating a project with starter scaffolds.
Aside from the files, explain left-over topics from previous chapter
here. Paste deploy, entry-points, pserve, waitress and stuff (or put
this in a new chapter?).
6. Dumbed-down chapters
We ask ourself at the end of every chapter, is the information
provided here enough for them to jump straight to the current docs
(via links at the end of each chapter)? If not, what do we do? Three
options:
- giving brief explanation at the end of each previous chapter. E.g:
explain configurator briefly at the end of one-file app chapter.
- dumbing down the current docs (or add some newbie-friendly preamble).
- give them dumbed-down chapters here?
It looks like the last option only works if we separate this starter
docs from current docs.
Never write something like pyramid.foo.Bar in the starter docs. If we
want to make it a hyperlink, just use Bar not the full dotted name.
Explaining imported things should be as simple as possible, like "we
import Response from pyramid.Response. Response is needed for lorem
ipsum bla bla bla. End". Delay detailed explanation as late as
possible (explain it at the end of the chapter, or just give them the
link to Response in current narrative docs).
IMO, always have all reference links at the end of the chapter. Some
people like to open-in-a-new-tab hyperlink in the middle of a
paragraph, but some people might find them distracting or wait to
finish the whole chapter before going somewhere else. I dont know,
worth considering maybe.
I think it would be better to keep the paragraph/code ratio small.
Save all the gory details for current docs. Also explain what approach
this starter docs has upfront. There will be some newbies who want to
have instant webapp with forms and db integration in 15 minutes.
Maybe, we can tell them pyramid, and this docs, do not provide that
and we can point them to external tutorials (pyramid-blogr). Put all
this upfront to minimize angry "pyramid obfuscates web development"
blog posts.
Those are some ideas for now. I'll be willing to review any beginner-level docs.
Regards
--
You received this message because you are subscribed to the Google Groups
"pylons-discuss" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/pylons-discuss?hl=en.
