Documentation sprint, April 12 - 13, 2008

We're having a mini-sprint to refactor the documentation this weekend. If you want to help out, join us in #django-sprint.

TODO

Well, a lot. See ​the notes on contributing to the docsprint. However, here are some specific things that can be done now (i.e. aren't dependent on other folks work:

• Add correct Sphinx markup to intro/ directory.
• Write intro/install.txt. It should be based on topics/install, but much much simpler -- geared towards folks just getting started. Python 2.5, sqlite should be the focus.
• Finish applying django-admin and django-admin-option markup in ref/django-admin.txt.
• (HUGE): break up model documentation (currently all in topics/db/models and ref/models/querysets into all the various outlined documents in ref/models and topics/db.
• (QUITE LARGE): break up forms documentation from topics/forms/index into the outlined content in topics/forms and ref/forms.
• Fix up generic views: adapt Chapter 9 of the Django Book (consider this TODO item my permission and license) into topics/generic-views; remove the intro material from ref/generic-views and just leave the overall reference.
• Add ​glossary directives for "important" terms. A very small starting list can be found ​in the contributing documentation, but there's many more candidates for glossary.
• Start looking at the generated index (look in _build/html/genindex.html after running a build) and improving it by adding ​index directives where appropriate.
• Fill in empty documents with content (most will just be moved from other places). Currently empty files:

      ./howto/newforms-migration.txt
      ./howto/split-models.txt
      ./howto/standalone-templates.txt
      ./howto/url-best-practices.txt
      ./obsolete/pagination.txt
      ./topics/db/managers.txt
      ./topics/db/queries.txt
      ./topics/db/sql.txt
      ./topics/http/auth.txt
      ./topics/http/generic-views.txt
  

• Find code blocks and make sure they're ​syntax highlighted correctly.

If you choose to do any of these items, remove it from above and add your name/IRC handle below.

Oh, one other thing:

• Add more items to this TODO list.

Who's doing what

Please indicate what you're working on below so that we can easily keep track.

• jacobkm -- hacking on the build system
• cramm -- adding cross-ref targets at the top of documents still missing it.
• jcd -- annotating ref/settings with targets.
• knmurphy -- moving over topics/templates to ref/templates/builtins and annotating with templatetag/templatefilter directives
• yml -- annotating ref/request-response
• jezdez -- adding module specific markup and description units to contrib/*
• knmurphy -- moving topics/middleware into ref/middleware
• jacobkm -- refactoring faq/ to have correct links
• SimonW -- refactoring template docs in to smaller files
• jcd -- adding :setting: xrefs through documentation
• knmurphy -- moving ref/django-admin.txt to ./howto/custom-management-commands.txt
• yml -- Replace all images (.. image:: and .. figure:: directives) with local image files -- right now they use absolute URLs to Django's media server. Images should be put in in _static directory next to the document they're used in. For an example, see internals/contributing.txt and the associated internals/_static directory.