Proposed new CKAN documentation outline, for comments

README.md

Aims:

• The structure/organization should be simple and immediately obvious so that:
  1. Readers can find stuff
  2. 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

outline.txt

- Overview
  (An introductory overview page describing the structure of the docs and
  introducing core CKAN concepts like dataset, resource, organization,
  filestore, datastore.)
- Contact
  (Contact page with links to mailing lists, irc, etc. The github README and
  ckan.org should both link to here for contact details, not repeat them.)
- Installation
  (Introductory paras, e.g. explain "install" vs "deploy")
  - Install from package
  - Install from source
  - Create an admin user
  - Load test data
  - Basic customization
  - Deployment
- Upgrading
  - Upgrading a package install
  - Upgrading a source install
- Core Features
  - Data Preview
  - Organizations & Auth
  - Apps & Ideas
  - Tags & Vocabularies
  - Form Integration
  - Linked Data & RDF
  - FileStore and File Uploads
  - Background Tasks
  - Email notifications
  - Page view tracking
  - Command Line (everything to do with paster commands)
- Extensions
  - Datastore
  - Multilingual
  - resourceproxy
  - stats
  - Data preview extensions
    - pdfpreview
    - reclinepreview
    - jsonpreview
  - Harvest
  - Spatial
- Theming
  (Everything you need to know to write a custom theme.)
- Writing Extensions
  (Everything you need to know to write an extension.)
  - Plugins toolkit
  - Plugin interfaces reference
- CKAN API
  - Action API
  - DataStore API
  - FileStore API
  - Legacy APIs
- Configuration Options Reference
- CHANGELOG
- Release Cycle
- CKAN Development
  - Contributing to CKAN
  - CKAN backend development guidelines
    - Backend testing
    - Python coding standards
  - CKAN frontend development guidelines
    - Frontend testing
    - Javascript coding standards
    - HTML coding standards
    - CSS coding standards
  - CKAN documentation guidelines
    - Contributing to CKAN's Documentation
  - CKAN i18n guidelines
  - Doing a CKAN release

Should Theming and Writing Extensions go under Extensions?

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)

@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.