[ckan-discuss] Fwd: Re: CKAN documentation plans - please comment!

[James Gardner]

Hi Anna,

Just wanted to say that you might be falling into the same trap here 
that everyone who attempts documentation falls into. If all we end up 
with is yet another documentation plan we won't have done any better 
this time than any of the other times we've attempted this ;). Having 
written a book myself I know that it is virtually impossible to do it 
with a consensus based approach so canvasing all this opinion will 
actually make your life harder. You need to be tough and with the 
remaining 6 days it would be far, far better to write *something*, 
(anything!), rather than try to be perfect. That's my 2 cents.

Cheers,

James



-------- Original Message --------
Subject: 	Re: [ckan-discuss] CKAN documentation plans - please comment!
Date: 	Fri, 17 Jun 2011 20:24:26 +0100
From: 	David Read <david.read at okfn.org>
To: 	Anna Powell-Smith <annapowellsmith at okfn.org>
CC: 	ckan-discuss at lists.okfn.org



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.

 From the wiki, these sections should move wholesale to the admin docs
(sphinx) "Administrative Dashboard" "Access_Control" "System
Administrator Guide" "Developer Guide".

http://wiki.okfn.org/ckan/ needs to be fully migrated and got rid of
since it is just confusing having it hanging around.

I could just make these particular changes I've suggested, but I think
it's better to have agreement first, followed by some divvying up all
the tasks. And having Anna take responsibility for the overall effect
is excellent.

Dave

>  This will probably stay on the wiki, but will hopefully become a full
>  guide in two sections: introductory (using the web front-end) and
>  advanced (API usage etc).
>
>  I won't focus on this as much, so please help improve it - either
>  by adding suggestions to the overhaul page, or simply by editing the
>  wiki!
>
>  best wishes
>  Anna
>
>  _______________________________________________
>  ckan-discuss mailing list
>  ckan-discuss at lists.okfn.org
>  http://lists.okfn.org/mailman/listinfo/ckan-discuss
>

_______________________________________________
ckan-discuss mailing list
ckan-discuss at lists.okfn.org
http://lists.okfn.org/mailman/listinfo/ckan-discuss

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.okfn.org/pipermail/ckan-discuss/attachments/20110621/8f119580/attachment.htm>