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

Tue Jun 21 12:31:22 BST 2011

hi James

heh - thanks for the warning!

Actually, what has consumed most time so far is simply working out what
CKAN, um, actually is and does. To an outsider it's not completely obvious,
which I guess is why we need ckan.org. Having installed it I think I get it
now :)

But good point, and thanks for giving me the green flag to Just Write.

best wishes
Anna

On 21 June 2011 12:15, James Gardner <james at 3aims.com> wrote:

> **
> 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> <david.read at okfn.org>  To: Anna
> Powell-Smith <annapowellsmith at okfn.org> <annapowellsmith at okfn.org>  CC:
> ckan-discuss at lists.okfn.org
>
> On 17 June 2011 18:21, Anna Powell-Smith <annapowellsmith at okfn.org> <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 listckan-discuss at lists.okfn.orghttp://lists.okfn.org/mailman/listinfo/ckan-discuss
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.okfn.org/pipermail/ckan-discuss/attachments/20110621/da6908ca/attachment.htm>