[ckan-dev] Documentation todo list for 2.0 release

Tue Mar 5 14:25:09 UTC 2013

We looked briefly at the disqus extension but it immediately raised all sorts of privacy concerns (especially for us as a gov't agency). I know it wouldn't have to be enabled, but +1 to the suggestion to leave it out of core. Spatial is a very common source of datasets, especially for us and data.gov, but with every extension you potentially increase the number of pre-requisites and complexity of setting up a basic CKAN. It's good for us, but maybe there's value in keeping the core clean and focused.

Ross 

-----Original Message-----
From: ckan-dev-bounces at lists.okfn.org [mailto:ckan-dev-bounces at lists.okfn.org] On Behalf Of Toby Dacre
Sent: March-05-13 4:24 AM
To: CKAN Development Discussions
Subject: Re: [ckan-dev] Documentation todo list for 2.0 release

Sean,

Thanks for this I think it is really important that this get taken on board and that you are given the resources to do at least some of the work you have outlined here.  Documentation always seems to be neglected and I think that this email goes along way to suggesting how we can improve what we have.  Better documentation should lead to less support needed and greater uptake of ckan.

On the one question I found

> 1. If the disqus, harvest and spatial extensions are so important that 
> we want to document them in the core docs, then move their code into 
> the core repo too, like multilingual and datastore. They can still 
> have their own pip-requirements files and setup instructions.
>

I'd be happy for harvest and spatial to move into core but really Adriá seems like the key player on these - disqus is basically spyware as far as I'm concerned and should always be an external extension.
On this subject I am also very keen to see recline moved to be an external extension due to it's rapid update cycle.

Toby

On 1 March 2013 17:58, Sean Hammond <sean.hammond at okfn.org> wrote:
> I've gone through the changelog, the docs, and some other sources and 
> made a list of missing and out-of-date doc pages, they're on github 
> issues with the CKAN 2.0 milestone and the docs label:
>
> https://github.com/okfn/ckan/issues?labels=docs&page=1&state=open
>
> Unfortunately there's 20+ pages to do.
>
> Something for the next sprint planning meeting I guess.
>
> Personally I'm in favour of doing most or all of this docs work, and 
> I'm happy to take on a lot of it myself. The docs are important and 
> they're in a state currently.
>
> Note that some docs have already been updated in pending pull requests 
> so I didn't make new issues for those, these include: The API docs, 
> Customizing Forms, Tag Vocabularies.
>
> Aside from specific pages that need work, some general documentation 
> tasks and questions. Sorry this is long and a bit of a braindump but I 
> think it'll be useful for reference:
>
> Overall organisation
> ---------------------
>
> Once all these pages have been written I think it'd be worth someone 
> reorganising the table of contents as well. Not all the information is 
> presented in the best order. For example, there's a page about 2/3 
> through the docs that tells you what a dataset and a resource is! Some 
> core concepts are probably just assumed and not explained at all. At 
> the least it's missing an overview of what CKAN is and what you can do 
> with it/what features it has at the start (outside input from someone 
> not a ckan dev probably needed here).
>
> As well as making it easier for users, reorganising the toc should 
> also make it easier for devs to add new documentation, if the 
> organisation is really clear and simple it'll be easy to see where a 
> new part should go, currently it isn't which puts people off from writing docs.
>
> Why does our table of contents have its own section titles, within the 
> table of contents itself? It means that if I want to link to the  For 
> CKAN Developers section for example, there's not a page I can link to, 
> instead I have to give an anchor-link to a title within the toc page.
> This isn't how a table of contents normally works. Take the Python 
> tutorial or library reference for example:
>
> http://docs.python.org/2/tutorial/index.html
> http://docs.python.org/2/library/index.html
>
> I would change this.
>
> Also. the front page of our docs has the table of contents in the main 
> body, and the same table of contents beside it in the sidebar! (but 
> formatted differently and with a different depth) Maybe we shouldn't 
> have the entire table of contents in the sidebar.
>
>
> What should go in the docs and what shouldn't?
> ----------------------------------------------
>
> Currently we don't seem to be making decisions consistently.
>
> - I thought that we didn't document the user interface, so there are 
> no docs at all for the Activity Streams, Follow or Dashboard features 
> (apart from the relevant action functions appearing in the action api 
> docs), but the Email Notifications feature requires some work from a 
> sysadmin to set it up, so that is documented:
>
>   http://docs.ckan.org/en/latest/email-notifications.html
>
> but some docs pages seem to break this rule, e.g. Linked Data & RDF is
> documented:
>
>   http://docs.ckan.org/en/latest/linked-data-and-rdf.html
>
> Maybe that one is acceptable since it's kind of a hidden feature that 
> you'd never find via the api? But Apps & Ideas is documented too:
>
>   http://docs.ckan.org/en/latest/apps-ideas.html
>
> the only excuse for that one is maybe that the config setting to turn 
> if off needs to be explained, but there's a separate page that lists 
> all the config settings so it could just go in there.
>
>
> Do we document extensions in the core docs or not?
> --------------------------------------------------
>
> We have some general docs about ckan extensions and how to write them, 
> and a list of officially-supported extensions (which should be moved 
> nearer to the beginning of the docs as part of a general list of 
> CKAN's features, not buried in the middle), but generally we seem to 
> document the extensions themselves in the README files in their own 
> git repos, not in the core docs. This makes sense to me, keep the docs near the code.
>
> The exception is core extensions that come in the ckan git repo, like 
> multilingual and datastore, those are documented in the main docs.
>
> But a few pages in the docs break this rule:
>
> http://docs.ckan.org/en/latest/commenting.html
> http://docs.ckan.org/en/latest/harvesting.html
> http://docs.ckan.org/en/latest/geospatial.html
>
> Note that each of those three extensions also has docs in its own 
> README file so we're duplicating docs here.
>
> I think there are two choices here (either of which is fine with me):
>
> 1. If the disqus, harvest and spatial extensions are so important that 
> we want to document them in the core docs, then move their code into 
> the core repo too, like multilingual and datastore. They can still 
> have their own pip-requirements files and setup instructions.
>
> 2. Or if not, then don't document them in core, except by linking to 
> them in a list of CKAN's features at the start, delete the above pages.
>
> But don't do a mixture of 1 and 2.
>
>
> Screenshots
> -----------
>
> These would make the docs much nicer looking and more informative, 
> some pages are just screaming out for one. Should we go and add them?
>
> If we keep all screenshots in a docs/scrots/ folder, then it should be 
> quite easy to update them when we release a new version of CKAN, 
> someone just needs to go through that folder and re-take them all.
>
>
> Google docs presentations, links to blog posts, etc.
> ----------------------------------------------------
>
> I want to go through and delete all these, replace them with normal 
> docs text. They break search engine hits, linking and 
> cross-referencing, printing/pdf version, accessibility, 
> maintainability, grepping the docs, having an offline copy of the docs, etc. etc.
>
> _______________________________________________
> 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

_______________________________________________
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