I'm embarking on a mission to refactor Django's documentation; this is where
you give me feedback about how much crack I'm smoking. Keep in mind that most
of this post fits into the "heads-up" category: if I'm not asking for feedback
on some point it's because I've made up my mind. Only argue with those points
if you *really* think you need to.
I've identified five types of people reading Django documentation:
* New users looking to get started or to learn new techniques.
* Developers looking to solve a specific problem.
* Developers looking for reference to a particular API.
* Experienced developers looking to build other frameworks on top of
Django using extension points (middleware, signals, contribute_to_class,
etc.)
* Contributors looking for information about Django internals and
workflow.
This leads me to identify five types of documentation we need:
* Beginner material (tutorials, getting started)
* Cross-sectional "how-to" material (specific walkthroughs of particular
techniques)
* Topical guides ("caching", "middleware")
* API reference ("HttpResponse.__init__")
* Internals and meta-documentation.
(This leaves out misc. stuff like release notes; I don't really think we need
to worry about those beyond stuffing 'em in a "misc" section.)
My breakdown of stakeholders is one place I'm looking for feedback. Am I
missing anyone? Is there a "type" of documentation I've not thought of?
This'll become the high-level organization of the docs, so getting it right is
important.
My thoughts on how we do on each section and how we need improvement:
* Beginner material: we've got a good amount if this in the tutorials,
overview, and installation guide. Some bits of those documents --
especially the installation guide -- ought to be broken out into
reference material.
* Cross-sectional how-tos: we've only got a few of these currently. This
is the area where bloggers are doing a wonderful job these days. The
problem with this blog material is that it usually doesn't every get
updated, so it eventually becomes obsolete. The task here will be to
identify the best of these articles and make them official parts of the
documentation. If we can get the original author to maintain the doc,
even better.
* Topical guides: we're awesome here; most current docs are organized
around one particular topic covered in depth. The only thing to change
here is to move detailed reference out of these documents into dedicated
reference docs. This will improve the overall flow of the topical
guides.
* API reference: like above, we're pretty awesome here, too. Again, though
the API reference needs to move to documents linked from the topical
guides.
* Internals: not so hot; in fact, we've really only got the contributing
document. Help is needed here.
Again, am I missing anything here?
By now you probably want more details. OK, here we go.
If you hung out with my at the PyCon sprint this'll probably make sense. If
not apologies, 'cause I'm gonna do a bunch of hand-waving now. Ask questions
where it doesn't make sense.
The main goal in refactoring is to break everything up into manageable chunks.
The model API document is over 30 printed pages -- finding anything useful
there is rapidly becoming impossible. Even worse, it's hard to tell if
something's gonna be found there or in the DB API -- quick, where are primary
keys documented?
What I'm planning on doing is some radical chopping. I'd turn the model
documentation into a bunch of different docs, laid out something like the
following (where each bullet point is a separate doc file/page):
* High-level overview: defining and loading models.
* Model definition reference
* Field types
* Relationships
* Meta options
* Writing managers
* "Special" model methods
* DB API reference (CRUD basics)
* Manager methods
* QuerySets / QuerySet methods
* Filter lookup options
* Following relationships
* Custom SQL
This is only a rough sketch -- please don't even bother critiquing it; it'll
change. I only include it there to give you a rough idea of what I'm intending
to do. And of course I'm not going to limit my work to models; I plan to do
something similar to all the documentation.
This is the main bit I'm looking for feedback on. Is this a good idea, or am I
on crack?
In the end, the basic idea will be that topical information will "flow" like
good prose should, but will link down into detailed reference where
appropriate. Each little bit of reference will have a canonical "location" in
the docs, so that every like to HttpResponse will go to the same place.
Of course, this'll require better tooling -- we're going to need to make sure
these links all work and maintain them correctly. More documents means we need
better indexing, searching, etc. Luckily someone else already wrote the
perfect tool for the job; it's called Sphinx (http://sphinx.pocoo.org/). It'll
do everything I want, and more. I'm not interested in using different tools,
so let's not discuss that. Suffice to say I've sketched out the code needed
and it's perfect; all the hard work is going to be in actually
rewriting/moving around docs.
Right. How will I do this, you say? Here's my plan:
* Using the outline from the existing documentation
(http://toys.jacobian.org/django/docoutline-r7392/), make a new outline
and figure out where each bit fits into the new regime. This doesn't
need to be in any way perfect or 100% complete; just good enough to get
started from.
* Following that outline, break up the existing docs. Copy/paste is fine;
no rewriting yet.
* A few areas will need top-level outlines/indexes. Write those.
* Go through each document and mark it up with all the gory metadata and
links. This is the part that'll take a crazy amount of work.
* Rewrite the website documentation tools to work under the new regime
(they'll already build standalone thanks to Sphinx).
Am I missing anything here?
So feedback is welcome, please give it. Volunteers are welcome, too, but I'll
probably not be ready to distribute work just yet. I need to finish the
groundwork, and I need to figure out how to best to work without totally
fucking up the existing docs.
Jacob
--~--~---------~--~----~------------~-------~--~----~
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?hl=en
-~----------~----~----~----~------~----~------~--~---
