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

Mon Jun 20 11:18:17 BST 2011

On 19 June 2011 17:18, Rufus Pollock <rufus.pollock at okfn.org> wrote:
> On 17 June 2011 20:24, David Read <david.read at okfn.org> wrote:
>> 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.
>
> Going forward I think we should ditch name 'developer docs' for what
> we are doing and use term (Administrator) Manual and Reference Docs
> (but I know we currently refer to these as developer docs ...)
>
>> 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.
>
> Right. This is an issue. Options:
>
> 0. Stay as we are
> 1. Have 2 wikis
> 2. Move wiki.ckan.net to wiki.ckan.org
>
> This also relates to a bigger conversation about confusion between
> CKAN the software and CKAN the service/community (i.e. ckan.net and
> associated subdomains). Almost everyone who does not know 'CKAN' well
> has reported this confusion which is probably made worse by using
> ckan.org and ckan.net for the different things.
>
>> 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.
>>
>> From the wiki, these sections should move wholesale to the admin docs
>> (sphinx) "Administrative Dashboard" "Access_Control" "System
>> Administrator Guide" "Developer Guide".
>
> I don't agree about Developer Guide. I personally think core developer
> stuff is not something that it is crucial to have in sphinx docs at
> the moment and can be more easily developed on the wiki.

Yes I agree a wiki is easier than sphinx for development processes
etc., although I think it is confusing when devs and admins are mostly
the same people, and half of their stuff is mixed in with the user
stuff on the wiki. It would be good to clearly separate, or not even
link to the dev pages from the user pages in this case.

>> http://wiki.okfn.org/ckan/ needs to be fully migrated and got rid of
>> since it is just confusing having it hanging around.
>
> I think it has been migrated and we should just remove now.

There are a whole bunch of ckan pages still on that wiki linked from
here for example:
http://wiki.ckan.net/Development which should be moved to the new CKAN wiki.

David

>
> [...]
>
> rufus
>