[ckan-dev] Docs draft
Anna Powell-Smith
annapowellsmith at okfn.org
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
More information about the ckan-dev
mailing list