> So feedback is welcome, please give it.
Breaking the huge documents into smaller chunks for readability is
good... but please do leave the original huge ones as well! There are
cases where "a huge document" serves more help than "a bunch of
smaller ones" and really has its worth.
Opening /cache/ or /db-api/ gives you a single document that has
*everything* on the cache/ORM access topic, without need to jump over
urls here and there; having two or three tabs opened in the browser
and covering the topics of the most current importance to you is much
more convenient, than opening two or three dozens smaller ones and
trying to figure out which tab has the document you need. And the huge
size of the document is not that much of a problem in the browsers
that support Ctrl+F or "/" hotkeys... all of them, I believe, with the
different degrees of convenience though.
It is not that I am representing the view *against* splitting the huge
documents. I am just raising a hand in a case if "document is broken
into shorter sections" will mean that "no good old long-sectioned
documents are available anymore". The best what could be having two
"builds" of the documentation made from the same sources - one having
long unsplitted sections, and one having short splitted sections. Kind
of a "devil advocate" - with the sincere incline to the devil side of
the long documents.
On 31 мар, 22:45, "Jacob Kaplan-Moss" <[EMAIL PROTECTED]>
wrote:
> 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 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
-~----------~----~----~----~------~----~------~--~---
