Aims:
- The structure/organization should be simple and immediately obvious so that:
- Readers can find stuff
- Devs know where new docs should go, or what docs need to be updated if they've change something
- Structure is more "flat" with less generic sections, hopefully this makes the structure clearer
- The stuff under the top-level heading "Installation" is meant to take you through a complete install, deployment and basic customisation, the idea is that we (the ckan dev team) would follow this when deploying new client sites, instead of having our own wiki pages etc.
- Probably Overview and Contact will be pulled into Sphinx from the top-level README file, so they will also appear on the github front-page
- Changelog is pulled-in from the top-level CHANGELOG file
- Contributing is pulled-in from the top-level CONTRIBUTING file, which also gets linked to from new github issue or pull request pages
Also see this email: http://lists.okfn.org/pipermail/ckan-dev/2013-April/004521.html
This also tries to take into account these google docs:
- https://docs.google.com/a/okfn.org/document/d/15DmZUpQA2XTjzsnB_vYFFZM3YUQ3UYtwUOhxWmzgCPc/edit#
- https://docs.google.com/a/okfn.org/document/d/1tvjcI1ctuQT6K26t1uGlNDdYUPWnG0WhVxkcJiHDcQw/edit#
Other considerations:
- There may need to be some end-user docs one day, eg. how to use the web interface to upload data or manage an organization. I think Gavin wants this sort of thing. This is not taken into account here yet
- People have also been asking for stuff about integrating CKAN with Drupal to go into the docs this is also ignored
This looks great, much clearer than now.
I agree with Nigel, to write a theme you'll need at list a basic understanding of how extensions work (eg include pubic andd templats folders). Also the frontend resources stuff (fanstatic) although maybe you already had included it there.
I would like to keep the actual docs for harvest and spatial out of core, as they are bound to change more often. I'm happy to keep an introductory page linking to the actual docs for each extension (right now the README, but soon proper sphinx docs as they have grown too big)