[ckan-dev] Docs draft

Tue Jul 26 19:58:56 UTC 2011

I forgot something important: many thanks to David Read, James Gardner
and David Raznick for their help with this.

Maybe there should be a call later this week to discuss anything
that's missing, etc? Might be more efficient than email.

best wishes
Anna

On 26 July 2011 20:14, Tim McNamara <tim.mcnamara at okfn.org> wrote:
> 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
>>
>
> _______________________________________________
> ckan-dev mailing list
> ckan-dev at lists.okfn.org
> http://lists.okfn.org/mailman/listinfo/ckan-dev
>