[ckan-dev] Docs issues prioritised

Tue Mar 12 17:34:24 UTC 2013

On 12 March 2013 17:12, Sean Hammond <sean.hammond at okfn.org> wrote:
> As agreed in the dev meetup earlier today I've gone through the docs
> issues on github and marked some of them high priority, we can assign
> these on Thursday and try and get through them this sprint.
>
> I ended up with 14 high priority docs tasks (maybe this is too many and
> we need to cut it down further??)

Thanks, I think we should still try to split this list into the really
critical ones (I'd say this maybe is about which ones would reduce the
number of support requests we receive) so we can do a round one and
then round 2.  I'd be happy to say that we cannot work on new stuff
until these are done if we are not given sufficient time.

>
> If we get these done then, including the docs that already seem
> up-to-date, we'll have decent, up-to-date docs for:
>
> - Overview of CKAN
> - Package Install and Upgrade
> - Source Install and Upgrade
> - Deployment
> - Theming
> - Using Extensions (just how to use them, not how to write them)
> - Tag Vocabularies
> - FileStore
> - DataStore
> - Multilingual
> - Email Notifications
> - Organizations (and auth)
> - Data Previews
> - API
> - Admin Dashboard
> - Paster Commands
> - Configuration Options (i.e. the config file)
> - CHANGELOG
> - CONTRIBUTING
>
> If we don't get time to also do the rest of the docs tasks and to do
> general reorganising and editing/polishing, then I think the docs will
> still look pretty shoddy and also the overall narrative and organisation
> will be quite confusing and contradictory.

I agree they do not show us in a good light

>
> Ideally we would have time to sort it all out.
>
> But failing that, my suggestion would be to delete all unfinished or
> out-of-date or just plain bad docs pages from the table of contents (if
> not actually deleting the files from git) leaving us with more or less
> just the stuff listed above.
>

Maybe this is a good approach

One question I have about the docs is who they are aimed at?  Are
these for developers/sys admins (real ones not ckan) or for users of
ckan.  I think sometimes this is not clear and that really doesn't
help.

toby

> I'd rather we put out incomplete docs but have what is there be of some
> quality, than put out a mess.
>
> (There are some other pages that I would keep even though they may not
> be completely up-to-date, mostly the For Developers stuff.)
>
> _______________________________________________
> ckan-dev mailing list
> ckan-dev at lists.okfn.org
> http://lists.okfn.org/mailman/listinfo/ckan-dev
> Unsubscribe: http://lists.okfn.org/mailman/options/ckan-dev