[ckan-dev] Documentation todo list for 2.0 release

Fri Mar 1 17:58:26 UTC 2013

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.