[ckan-dev] Docs draft

Tue Jul 26 18:56:06 UTC 2011

Hi all

I've just uploaded my revised docs to http://docs.ckan.org/

And checked the changes in (en masse) at https://bitbucket.org/AnnaPS/ckan

1. Things I have done:

* rewritten the Sphinx docs to be task-focussed and user-facing,
rather than developer-facing
* moved everything task-focussed off the wiki into the Sphinx docs
* moved everything that looked like 'background information' to the
wiki, e.g. http://wiki.ckan.net/Load_Testing and
http://wiki.ckan.net/Making_changes_to_model_code
* split the Sphinx docs into two logical halves: basic sysadmin
information (requiring package install only) followed by more advanced
(requiring developer install)
* given particular attention to the following sections:
 * http://docs.ckan.org/preparation.html - brand new section on
setting up a suitable Ubuntu system
 * http://docs.ckan.org/theming.html - rewrite
 * http://docs.ckan.org/loading_data.html - removed all but very
high-level overview (on James's advice)
 * http://docs.ckan.org/paster.html - removed ex-commands
 * http://docs.ckan.org/authorization.html - tried to clarify
 * http://docs.ckan.org/i18n.html - tidied up
 * http://docs.ckan.org/configuration.html - moved into logical sections
 * http://docs.ckan.org/api.html - not much here, but flagged up that
the API index page is not actually the latest reference
 * http://docs.ckan.org/plugins.html - not much here except
copyediting and tidying (scary section)
* added many cross-references throughout
* link-checked throughout
* copyedited and formatted throughout.

2. Things I still need to do, once the dev team is happy with these docs:

* Delete and forward deprecated wiki pages
* Forward the existing Sphinx docs at http://packages.python.org/ckan/
to http://docs.ckan.org
* Update http://ckan.org/documentation/ with details of the lovely new docs

3. Things I am not particularly happy about:

* API documentation is split between the wiki and these docs, in a
confusing way. I think the API tutorial on the wiki should really move
on to http://datahub.org and become part of the CKAN you give to
customers (as should everything currently in the User Guide).
* Extensions documentation is also split between the wiki and these
docs - I'm not sure of the best place to put details of individual
extensions.
* We don't have a good 'How to become a CKAN developer' intro, as
James requested.

Thoughts welcome.

4. What I need you to do:

* Let me know if I have broken anything or missed anything out.
* Let me know your thoughts on (3)
* Perhaps one person could give the entire doc a technical review.

And most importantly, we need to make sure that the docs stay up to
date. I suggest:

* There should be a policy on what information goes where.
* Someone in the CKAN team should be responsible for a regular check
of both wiki and Sphinx docs.

best wishes
Anna