[ckan-dev] Post-2.0 documentation status

Mon May 27 11:21:27 UTC 2013

Hey all,

Now that 2.0 is out (with all the docs work we did in the last couple of
weeks before the release) and we've got draft pull requests for the docs
reorganization [1] and the documentation guidelines [2], I've gone over
the docs issues on github [3] and updated them.

1: https://github.com/okfn/ckan/pull/769
2: https://github.com/okfn/ckan/pull/942
3: https://github.com/okfn/ckan/issues?labels=Docs&state=open

There are a lot of docs issues on there, a lot of them are small things,
but there's a few big ones. As far as getting our existing docs up to
standard, the remaining big tasks, as I see it, are:

- Better docs for writing extensions: https://github.com/okfn/ckan/issues/943
I'm hoping to work on this next sprint.

- Better docs for each of the plugin interfaces, with an example plugin
with tests for each. This is a huge job as there are many plugin
interfaces. I haven't created github issues for all of them yet.

- Better docs for theming: https://github.com/okfn/ckan/issues/944
I'm thinking maybe see how improving the extensions docs goes, and then
consider what to do with the theming docs.

- API tutorial? I haven't created an issue for this one as I'm not sure
whether we really want it or not. But just like we want an extension
tutorial with an example extension and a theming tutorial with an
example theme, maybe we should have an api tutorial with an example api app?

This would be a fully working example app or script that actually does
something useful and that has tests.

Probably see how the new extensions and theming docs go, and then
consider if we want to do something similar for the API.

- i18n. We really don't have very good docs for translators. Related:
we're using Transifex wrong, the need for better i18n-related coding
standards for programmers, the need for better tests for i18n-related
issues. There are various github issues about this currently, here's one
of them: https://github.com/okfn/ckan/issues/909 (we probably want an
i18n label to collect them)

- We want to get the configuration options, paster commands and plugins
toolkit docs working through autodoc:
https://github.com/okfn/ckan/issues/847
https://github.com/okfn/ckan/issues/765
(there's no github issue for sorting out how configuration works but I
think Toby's working on something)

- Now that we have documentation guidelines, and maybe once we've got a
couple of nice pages done that exemplify these standards, we should
probably go over all the existing docs and edit them for consistency and
clarity etc. I think there are lots of problems, and I'm not just
talking about spelling and grammar but also stuff like just failing to
explain to the user what a feature is and why they'd want to use it,
pages being badly organized, etc. A consistent style and set of
subsections for documenting a feature, should help a lot. Not a high priority
immediately though.

- Finally, I still think we have some undocumented features, though I
don't know how many.

In the reorganised docs above, the documents under Features in the
table of contents are just the feature documents that already existed,
organised into one section. With a couple of exceptions, so far we've
only documented features that require some setup or configuration.
Features that just work 'out of the box' have not been documented.

We've always had a policy of not documenting the web interface, so out
of the box features that can be used via the web interface are not
documented. Mark's currently working on a user guide that might address
that.

But what I'm talking about here are features that work out of the box
without any setup or config, but that are not discoverable via the web
interface. Things like params that you can type into the search field or
URL bar to do a complex search, or the RSS feeds for search results.

*Are* there any features like this that are undocumented, and that we
want to add docs for?