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

[Rufus Pollock]

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.

> 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.

[...]

rufus