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
@nigelbabu I think theming is actually a separate topic. You can do theming via an extension, but (I think) you can also just set extra_template_dirs and extra_public_dirs in your config and get full theme power that way. @johnmartin Can you confirm this?
Writing Extensions can probably go as the last thing in the _Extensions chapter though yes, but it has a different audience (devs who want to write an extension vs users who just want to use them) and is probably a large topic on its own, so may deserve a top-level entry of its own. Or maybe not.
@amercader Re docs for harvest and spatial (and external, officially supported extensions generally) I haven't really decided what to do with these yet, they probably need to be at least listed in the core docs somehow, it could just be a page with a link to the extensions' README (and that's what it will probably be for 2.0), longer term it could perhaps be done with InterSphinx.