[ckan-dev] Docs draft

[David Read]

On 26 July 2011 19:56, Anna Powell-Smith <annapowellsmith at okfn.org> wrote:
> Hi all
>
> I've just uploaded my revised docs to http://docs.ckan.org/
>
> And checked the changes in (en masse) at https://bitbucket.org/AnnaPS/ckan
>
> 1. Things I have done:
>
> * rewritten the Sphinx docs to be task-focussed and user-facing,
> rather than developer-facing

This is good organisation and very a useful improvement - great stuff Anna!

Some very minor suggestions are at the bottom.

> * moved everything task-focussed off the wiki into the Sphinx docs
> * moved everything that looked like 'background information' to the
> wiki, e.g. http://wiki.ckan.net/Load_Testing and
> http://wiki.ckan.net/Making_changes_to_model_code
> * split the Sphinx docs into two logical halves: basic sysadmin
> information (requiring package install only) followed by more advanced
> (requiring developer install)

This works well.

> * given particular attention to the following sections:
>  * http://docs.ckan.org/preparation.html - brand new section on
> setting up a suitable Ubuntu system
>  * http://docs.ckan.org/theming.html - rewrite
>  * http://docs.ckan.org/loading_data.html - removed all but very
> high-level overview (on James's advice)
>  * http://docs.ckan.org/paster.html - removed ex-commands
>  * http://docs.ckan.org/authorization.html - tried to clarify
>  * http://docs.ckan.org/i18n.html - tidied up
>  * http://docs.ckan.org/configuration.html - moved into logical sections
>  * http://docs.ckan.org/api.html - not much here, but flagged up that
> the API index page is not actually the latest reference
>  * http://docs.ckan.org/plugins.html - not much here except
> copyediting and tidying (scary section)
> * added many cross-references throughout
> * link-checked throughout
> * copyedited and formatted throughout.
>
> 2. Things I still need to do, once the dev team is happy with these docs:
>
> * Delete and forward deprecated wiki pages
> * Forward the existing Sphinx docs at http://packages.python.org/ckan/
> to http://docs.ckan.org
> * Update http://ckan.org/documentation/ with details of the lovely new docs
>
> 3. Things I am not particularly happy about:
>
> * API documentation is split between the wiki and these docs, in a
> confusing way.
> I think the API tutorial on the wiki should really move
> on to http://datahub.org and become part of the CKAN you give to
> customers (as should everything currently in the User Guide).

I say collect the bits of API tutorial onto the wiki and just have the
reference in sphinx. Clear cross linking would be good here.

I think it is good to have User Guide constantly updated in the wiki
rather than distribute them with the software frozen. The API
reference might be an exception though.

> * Extensions documentation is also split between the wiki and these
> docs - I'm not sure of the best place to put details of individual
> extensions.

Since these are springing up all the time we should have the list and
details of each one here, and the general info in the sphinx docs with
suitable links.

> * We don't have a good 'How to become a CKAN developer' intro, as
> James requested.

Does this cover it?
http://wiki.ckan.net/Becoming_a_CKAN_Developer

> Thoughts welcome.
>
> 4. What I need you to do:
>
> * Let me know if I have broken anything or missed anything out.
> * Let me know your thoughts on (3)
> * Perhaps one person could give the entire doc a technical review.

I've had a go through this quickly and it looks good and covers all
the main bases I can think of.

>
> And most importantly, we need to make sure that the docs stay up to
> date. I suggest:
>
> * There should be a policy on what information goes where.
> * Someone in the CKAN team should be responsible for a regular check
> of both wiki and Sphinx docs.

Sure, I can take that on with my role.

Dave

"Database Dumps
It’s often useful to allow users to download a complete CKAN database
in a dumpfile."

This section should probably mention the "db dump" command as well as
"db simple-dump-json/csv". db dump is good for backups, to replicate
the database completely, including users, their personal info and
apikeys, and thus would be kept private. The simple dump is intended
to be used a public listing of the packages but no user information.
Note all packages are still dumped, including deleted packages and
ones with strict authorization.

"licenses_group_url" can go under form settings. site_title,
site_descriptions, site_logo dumps_url & dumps_format can better go
under Frontend Settings.

"Note This section contains general information about the CKAN API. If
you are looking for API documentation, please see CKAN API Version 2."
I don't think this wording is at all clear. This page is the CKAN API.
There's a very basic difference between v1 and v2 and this could be
explained in a paragraph, and the full details of the API could be
inserted in this page. When v3 comes out then all the v1&v2 stuff
become displaced to elsewhere.

The "Add Extensions" page doesn't seem 'advanced' in my book. People
should install extensions right after they install CKAN and customise
the site's title, rather than being reserved for CKAN developers.

"Use Buildbot" maybe should be "Install Buildbot" to differentiate
from people wanting to use the buildbot to find out if the build has
broken?

"We discuss large changes and new features on the ckan-discuss mailing
list." I think this should also mention ckan-dev list, which is for
the CKAN coders to discuss code changes.

I disagree about deleting the stuff about creating loaders.