On Thu, 2007-10-18 at 19:18 -0500, Jeremy Dunck wrote: > Devs, > I'd like to improve the quality of Django's documentation. > I'm sure there will be many opinions on what "improvement" would mean. > > I'd like to solicit ideas from django-users regarding how people use > the docs and wish they were different. > > OK? I don't want to start the torrent of suggestions and demands if > people here want to exercise more control. :)
I suspect this is going to be a fairly frustrating exercise. People tend to want documentation that targets their own current level of skill and current way of working. Those two factors are all over the map and I'm not sure they're uniformly represented on django-users (a large number of questions come from people who aren't really familiar with Python programming for example, skewing the bar a bit low in the skill area). At least help them understand that (a) understanding increases, not the other way around, so pitching too low means you grow out of the documentation and it ends up helping nobody, (b) the difference between tutorial and reference docs and why both absolutely have a right to exist, (c) the benefits of extending, rather than supplanting exist documentation if somebody wants "easier" or "slower paced" changes, for examples. I don't think you're going to come up short on suggestions. Whether they are things we want to change will have to wait until we know what they are. I don't think this is something we promise in advance because I've seen some truly wrong-headed suggestions for doc changes on django-users over time -- things that would improve it for a small corner of the userbase at the expense of making things much worse for regular, experienced users. At the least, though, an exercise like this would give us a chance to collect some points into one place. Malcolm --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to django-developers@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/django-developers?hl=en -~----------~----~----~----~------~----~------~--~---
