[OK, this is longer than I intended. Sorry 'bout that. :-( Short version: yes, I agree. Focus on the organisation, too; we already have a lot of content; people apparently don't read the docs anyway; how we can kickstart this a bit; and some clues from other projects I've help on and hung around.]
On Sat, 2006-06-17 at 23:24 -0500, James Bennett wrote: > I've had some thoughts bouncing around in my head for a while about > Django's documentation, and I think it's time to finally commit them > to tangible form, so here goes: [...] > So I got to thinking about reforming Django's documentation, and > basically came up with three types of documents that I think we need: Prologue: I'm not sure why you titled this "reform", since I think it's pretty much a natural extension of where we are travelling already. Just attempting to lay out and possibly coordinate the road-map a bit more carefully. One problem is that even a large table of contents makes it hard to find what you are looking for. So how do we manage the fire hose of information? (This is fundamentally hard, I think -- the slides at [1] are from a talk I gave about this same problem in the "desktop" space last year. Most of the points I make there -- particularly the "bad" ones -- carry over to something like Django.) [1] http://www.pointy-stick.com/desktopcon-2005/ In what follows, take it as read that I agree with your ideas and most of your hypothesis -- the current documentation is pretty good and comprehsnive. Witness how many times a correct answer to a mailing list query is a URL pointing to the existing documentation (but don't think about how many times it's the same URL you posted three days ago; that just gets depressing). I'm going to approach this from the direction of what do we have now and how can we extend that. > > 1. High-level overviews of Django, both in the form of tutorials and > in documents that look at Django as a whole to show how the different > parts fit together. This would be a great starting point for new > Django users. Agree. The current tutorial clearly works for some people. But everybody learns in different ways and repetition doesn't hurt, either. So agree that we could use some more things here in the tutorial department. I don't see a problem with having these scattered around various places in the web initially. How things fit together is something we don't entirely have at the moment. Your detailed "lifetime of a request" post fills in a large hole here. There are a few other summaries like this I can think of, too, mostly shorter things that answer some of the common queries we are seeing like - where can I put my views? (anywhere, because they just have to be importable and callable) - where do templates go? (it's in the templates-python docs, but easily overlooked) - and so on... Challenge for document writers: what do we want to do? How to avoid repetition? How to track what we've done? Where to put it? I guess these are the kind of things you had in your point #3. > 2. Lower-level documentation of the individual pieces, featuring as > obsessive a level of detail as possible. Experienced Django users, and > experienced web developers in general, will get a lot of mileage out > of this. I would have thought that many of the existing docs tend to fall into attempting to fill this category somewhat. And that can get confusing. Because it's maybe not enough detailed for the very experienced and "Too Much Information. Make It Stop. Aargh!"(tm) for people starting out. Although, if I step back and try to be objective, I think we probably get things pretty right for the people getting started who want to do more than just generic views and admin interface. I'm not entirely sure what you (James) have in mind here, but I am thinking something like API reference docs, but not auto-generated, since they are less than useless without some summary wrapping and guide for tourists. There's just too much machinery that cannot be differentiated from real public methods inside Django for auto-generated to not be confusing. Something else that falls into this category is documentation for developers. Things like - where are things in the source code - Your "lifetime of a request" write up is in this area. - What happens when a model is constructed - How do field classes work? How do we write new ones? - What were the developers smoking when.. (no, wait... better leave that one out). These don't have to be too detailed, since it's fair to assume that if you are wanting to hack on Django you are capable of opening up a source file and reading. And it is Python, after all, so the bar is set pretty low. > 3. More documents in the line of the "solving specific problems" items > we already have. This can cover a lot of things, from specific types > of server setups to implementing particualr features to general > "design patterns" and conventions for Django-based development. How different is this from your first point? I don't see a huge distinction here, so probably I'm missing something. > Obviously this would be quite a bit of work, and I'd be happy to > devote what free time I have to helping write all this up. I think in > the case of the third group of documents it'd also be great to solicit > submissions from the Django community in general, both for topics that > need to be covered and for writeups of things people have done. For many of these things (write-ups of what's been done or solutions found), more active use of the Wiki would help. When somebody finds a solution, write it up. Props to guys like Coulix who do take the time to write up their findings (e.g. free comments and using Ajax with Django). A few people should periodically devote some time to checking things are somewhat organised. It's a little tricky to find things at the moment for some items (particularly because it seems to want to give me every Trac ticket ever made since Moses was a lad whenever I search for something). I suspect we aren't that short of documentation, even at the moment. We are probably a bit short of organisation in this area, though. > Anyone else have thoughts/suggestions on this? Any other volunteers > out there who want to help out? No. I think you should do it alone. It will help keep things consistent. And you should work faster; I can't believe you've waited this long and still haven't fixed whatever this problem is. :-) Concrete suggestion time: let's start a page in the Wiki listing, say, document titles (probably the easiest way to be as specific as possible) that we think we need. Group them into the sorts of categories you have above -- tutorials, overview, developer docs, API reference, workflow examples, common problems. Then we can put our names next to them as we start to write them or track them down. Some of these will already exist -- either on the Big Wide Web or in the Wiki already. We can probably even make a reasonable stab at putting a "how hard is it to write this" stamp on many of them so that anybody who wants can pitch in. Something to keep an eye out for: as more people start to contribute things, we might find we need a "word list" in order to use the same words for the same concepts. Probably not going to be a huge problem here, since everybody tends to use "template tag" and "filter" and "middleware" in the same way. More of a problem in projects like GNOME and KDE where you want to standardise on "desktop" vs "workspace", etc, just to keep things consistent. But we should keep a watch out for any easily confused or abused terms. This also helps translators a lot. An early thing to do when thinking about translating the documents (and even strings in the code itself) is to translate the word list (and then discover that some words don't have easy translations into Persian or Welsh or whatever and make a "translation team" decision about what to use in those places). Paolo and Ymasuda might be able to already identify some words we need to "define" pretty carefully in a glossary. Regards, Malcolm --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Django developers" 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-developers -~----------~----~----~----~------~----~------~--~---
