[ckan-dev] Docs draft

[Anna Powell-Smith]

Thanks for the review and all these notes, David.

James & I deleted the stuff about manual installation and loaders on
the grounds that:

1. Manual installation: We shouldn't be telling anyone to install
manually unless they really really want to, in which case they'll
probably already know how to do it
2. Loaders: How you use loaders is entirely dependent on the type of
data you have, so you should talk to ckan-dev before starting

Perhaps it would be better to keep both sets of instructions, but flag
them up with prominent warnings saying respectively "Use manual
installation at your own risk" and "Talk to ckan-dev for advice before
using loaders". Would that be better?

It's also possible that I've totally misunderstood what James said.

Other comments below.

On 26 July 2011 21:30, David Read <david.read at okfn.org> wrote:
> On 26 July 2011 19:56, Anna Powell-Smith <annapowellsmith at okfn.org> wrote:
[snip]
>> 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.

OK, will add, thanks.

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

I think one UX improvement or inline help is worth 10 wiki pages - but
that's outside the scope of this project, I think, and something for
CKAN to think about more broadly.

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

OK - so add the entire list? And update the "publishing an extension"
instructions to say "you should also add the name and details of your
extension to our list in these Sphinx docs, and add a more detailed
guide on the wiki"?

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

I renamed this from "Mercurial", but I'm not sure it covers
everything. I'll get hold of James to find out.

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

Thanks.

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

Excellent - will chat to you separately about policy.

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

OK.

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

OK.

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

Yep, agree - I'll move all the v2 docs into this page.

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

(I believe) you have to have done the 'developer installation' to
install an extension, because you have to activate a Python
environment. Hence my putting it here, with all the other things that
require a developer installation. However I believe the medium-term
plan is to start packaging extensions, so this section will be able to
move up, as you suggest.

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

OK.

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

OK.

> I disagree about deleting the stuff about creating loaders.

See top of this mail.