[ckan-discuss] CKAN documentation plans - please comment!

Fri Jun 17 20:24:26 BST 2011

On 17 June 2011 18:21, Anna Powell-Smith <annapowellsmith at okfn.org> wrote:
> Hi all,
>
> I'm working on CKAN documentation at the moment - trying to make the
> (generally excellent, but scattered and sometimes outdated) existing
> docs more coherent and accessible.
>
> Rufus and I have just audited the current CKAN documentation, and this
> is how we propose to update it:
>
> http://wiki.ckan.net/Documentation_Plans#Suggested_overhaul_2011-06-17

The overhaul looks good. A few things need moving, and I quite like
the splitting up of the developer docs into 'administration' and
'reference' sections.

I've added some comments on developer docs ticket, based on the later
versions in the repo. Mostly agreements, but I think ditching the
forms stuff is a bit rash. http://trac.ckan.org/ticket/1192#comment:1

We could do with documenting paster commands like 'db update' and 'db save'.

And I saw recent comments about unifying much of the install docs
between README and deployment.rst, which sounds good.

> Please get in touch if you have any thoughts or concerns - I'll be
> working on ckan.org, the administrator and reference guides over the
> next couple of weeks.
>
> We also need your input on the user manual for CKAN, which is
> currently the User Guide section at http://wiki.ckan.net/Main_Page

ckan.org is for the software, and ckan.net is a particular service. So
why is the universal CKAN user guide on a subdomain of ckan.net?
Surely ckan.org is better? Or is that technically difficult? There are
a few bits specifically about conventions for ckan.net, so these might
stay here, although having two wikis may be confusing.

I'd say that the User Guide needs more work than the Developer guide.
It seems like a list of little bits of info, not very well joined
together.