[ckan-dev] Docs issues prioritised

Tue Mar 12 18:55:11 UTC 2013

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

Alright, on Thursday lets start by going over the 14 and deciding which
can be removed from hi pri, then we can go over the surviving ones and
assign them.

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

My understanding is that they're aimed at people who'll be doing
any or all of:

- Installing, deploying, configuring, administering, upgrading a CKAN
  site. So they cover everything about installation, deployment, paster
  commands, config file settings, etc. Any features that do not work
  simply 'out of the box' but require any setup or config must be
  covered. And also the changelog is probably important to these people.
- Customising CKAN: the theming and extensions docs.
- Building on CKAN: the API docs.
- Developing for CKAN core: the For CKAN Developers stuff.

They're _not_ for general users of CKAN so they don't cover things like
how to use the web interface to add a dataset etc.

As I pointed out there are some sections where we seem to have deviated
from this general rule and documented frontend user features (albeit
extremely minimally), these sections stick out as all the other frontend
features are not documented or even mentioned, my take on it is we
should just delete these sections (unless we're going to go the whole
way and document the frontend).