I've been using the docs and haunting this list for a while and I think I have a more-or-less new-user perspective. First of all, the docs are great especially when compared to other stuff out there for other kit. But if we (er, not necessarily me) are going to hack on the docs we need an objective. There is so much there which is valuable as- is it would be best to try for something which isn't there at the moment.
The community benefits and the Django Foundation benefits if the community grows. It can only grow if it is easy to get started for newbies. Hence, I'm thinking they should be the target audience for any new docs. We already have the mindset that flexibility is king and that is sufficient to draw gurus from other languages/frameworks. Now we need a parallel mindset which says "easy" is super-cool too. I know that all the answers for newbies are already out there for the googling but it would be nice to say in one place "this is how to do it if you are new to Django". So nice in fact that this could be the objective for any new docs. If we started with some common-ish real-world scenarios and associated user requirements and did a standardised chapter on each scenario I believe new users would fall in love with Django in droves. Most gurus would hate to convert such scenarios into sets of howto instructions because there would be too many imponderables which might influence design and how they might do it. However, new users need to get started and that is the sole objective proposed here. These docs should therefore advertise a fixed, standard set of assumptions which sit between trivial and massive in order to reduce those imponderables and thus allow sensible, easy, non-magical, DRY approaches to each scenario. The last section of each scenario should be a list of suggested google phrases or search queries to acquire more information on other potential solutions for this and similar topics. In addition to specific references, this means new stuff should turn up as time passes. The nice thing about such a set of docs is that everything has been done properly already by someone on this list. It is just a matter of nominating a scenario and asking for contributed solutions. This means the docs proposed here only needs an editor pick the eyes out of contributed solutions and minimally write them up so newbies can understand what is happening. The entire list can technically review each chapter. Just a thought Mike On Aug 3, 9:44 am, Russell Keith-Magee <[email protected]> wrote: > On Tue, Aug 2, 2011 at 6:43 PM, eset <[email protected]> wrote: > > hi, > > > I am new to the Django list but I am a django fan (we dev with Django > > forwww.booki.cc)... anyways I wanted to encourage the Doc team and > > individuals on the list to apply for the GSoC Documentation Summit > > (details below): > >https://sites.google.com/site/docsprintsummit/ > > > You can apply as an individual or a group. Applications close Friday > > (5th), application process takes about 2-5 mins :) > > Hi Adam, > > Thanks for drawing our attention to this. This sounds like a great > opportunity to hack on Django's docs -- I'll see if we can shake loose > some volunteers to attend. > > For anyone > > Yours, > Russ Magee %-) -- You received this message because you are subscribed to the Google Groups "Django users" 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/django-users?hl=en.
