[ckan-dev] Documentation todo list for 2.0 release

Tue Mar 5 09:23:47 UTC 2013

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