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). 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 -- http://kusut.web.id -- 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.
