[ckan-dev] Docs draft

Wed Jul 27 11:12:09 UTC 2011

If you keep both, please make sure that the debian way is clearly labeled
"this is the DEFAULT route"
and the manual way
"this is the DEPRICATED/FALLBACK/EXPERIMENTAL route".

On 27.07.11 12:49, John Glover wrote:
> I strongly agree with David that the manual instructions should
> be kept along side the others. For one thing, there are developers on
> other platforms that might want to play around with CKAN locally, it
> does not require Ubuntu as stated in the docs.
> 
> John
> 
> On 27 July 2011 11:41, Anna Powell-Smith <annapowellsmith at okfn.org> wrote:
>> 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.
>>
>> _______________________________________________
>> ckan-dev mailing list
>> ckan-dev at lists.okfn.org
>> http://lists.okfn.org/mailman/listinfo/ckan-dev
>>
> 
> _______________________________________________
> ckan-dev mailing list
> ckan-dev at lists.okfn.org
> http://lists.okfn.org/mailman/listinfo/ckan-dev