[ckan-dev] Docs draft

Tue Jul 26 19:14:12 UTC 2011

Splendid work.

On 27 July 2011 06:56, Anna Powell-Smith <annapowellsmith at okfn.org> wrote:
> 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
>
> _______________________________________________
> ckan-dev mailing list
> ckan-dev at lists.okfn.org
> http://lists.okfn.org/mailman/listinfo/ckan-dev
>