From CKAN

This is a plan for improvements of Documentation as of 2011-06 and resulted in implemention during 2011-07 as ticket http://trac.ckan.org/ticket/1142

Contents 1 Suggested overhaul 2011-06-17 1.1 What we should have 1.2 Where we should have it 2 Original Outline 2.1 Introduction 2.2 Documentation for Personas 2.2.1 Procurers 2.2.2 Developers 2.2.3 Data wranglers 2.2.4 Publishers 2.2.4.1 Administrator's Guide (including install) 2.2.5 Curators

Suggested overhaul 2011-06-17

This is a suggested plan for the revision of CKAN documentation.

What we should have

We thought about this by user role and the priority of providing documentation for each:

• Procurers (high priority): 'Glossy' intro (why use CKAN, features), with shiny two-page PDF. Use http://www.cyclestreets.net/localauthorities/ for inspiration.
• Administrators (high priority): Administrator Manual and Reference Docs with everything you need to know if you're running your own CKAN: installation, deployment, theming, configuration.
• End users, both basic and advanced (medium priority): basic guides on how to use WUI, more advanced tutorials on API, data upload etc.
• Contributors to core (lower priority) - extensions and API (e.g. examples of how to load packages... talk to developers for this). How to become a CKAN developer, etc. Deferred for the moment.

Where we should have it

• Wordpress site at ckan.org: Only info hosted within Wordpress is glossy stuff for procurers (but we have a subdomain that is for developers, see below).
• Wiki at http://wiki.ckan.net/ - User Manual here. Idea is that it's easy for the community to edit, and may feed the administrator manual too. Split into two sections: intro and advanced. We should ask the community to contribute to this and suggest what's missing.
• Sphinx docs currently at http://packages.python.org/ckan/ - administrator docs here. Keep core stuff in Sphinx to match releases etc. Re-theme quickly to match Wordpress site, and move from packages.python.org to docs.ckan.org. Split into two sections, Admin and Reference. Convert as described at http://trac.ckan.org/ticket/1192
• CKAN.net: add a new FAQ for users, and link to User Manual on wiki from there and from site footer.

Relevant tickets: http://trac.ckan.org/ticket/1142 (docs overview ticket, also has long-term docs wishlist) and http://trac.ckan.org/ticket/1192 (Sphinx docs update).

Original Outline

Introduction

Documentation should be delivered with consideration given to the "right" place to bring together all the bits of documentation currently in existence. A ckan documentation website managed via a CMS or a wiki? If a wiki, do we need templates and a documentation metaguide to ensure some consistency? Perhaps it should all be in sphinx, or restructuredtext in bitbucket, or...?

The first deliverable for this phase should therefore comprise some kind of canonical structure for organising / making sense of existing documentation, with at least stubs pointing to all the existing stuff.

Secondly, to develop new, core documentation oriented towards the enterprisey end of the spectrum. It should prioritise the System Procurer and Data Publisher personas at http://wiki.ckan.net/Development

As such, it should cover, in a very concise way, probably with pictures:

1. What is CKAN
2. How it differs from competitor software -- what makes it better or worse
3. What’s involved in getting started with it (possibly links to sample sites, etc)

If there’s time, it should go on to cover:

1. A roadmap for getting an install running
2. software installation
3. theming the instance
4. extensions to consider
5. getting data in (basic user guide but also admin guide to authorization and user management)

The above is specifically with reference to:

1. the personas at http://wiki.ckan.net/Development (written by Seb)
2. FAQs and other end-user documentation at http://wiki.ckan.net/FAQ, http://wiki.ckan.net/Managing-Data-Packages, http://wiki.ckan.net/Searching_Packages, http://wiki.ckan.net/Creating_and_editing_Packages (written by Lucy)
3. The developer documentation (maintained as sphinx alongside code) http://packages.python.org/ckan/
4. Developers’ section of the wiki http://wiki.ckan.net/Development
5. Any other bits of the wiki

Documentation for Personas

What follows are some notes organised by persona. These are some rough working notes, to be improved upon...

Procurers

1. CKAN 1-page overview
2. Available extensions: http://wiki.ckan.net/Extensions but also have a look at repos with “ext” in name at https://bitbucket.org/okfn and email ckan-dev if there are gaps. Some are written up in blog form at ckan.org, e.g http://ckan.org/2011/05/20/follower-extension-for-ckan/, http://ckan.org/2011/05/16/storage-extension-for-ckan/, http://ckan.org/2011/04/18/new-analytics-extension-released/
3. Feature comparison grid. See https://spreadsheets0.google.com/spreadsheet/ccc?authkey=CLWu1cgP&hl=en_US&key=tYiwc9kUVLLlALOQEzFqujw&hl=en_US&authkey=CLWu1cgP#gid=0 for starters, but this isn’t really a complete list or a matrix suitable for decision makers
4. Benefits of CKAN: open source, collaboration with other bodies who are also using it (list them... DataGM, DataNL, ask Jonathan Gray). See http://wiki.ckan.net/CKAN_Instances_we_Consult_on, http://wiki.ckan.net/Instances and talk with developers.
5. Compare with Socrata website (drives data.gov)

Developers

1. 1 page overview
2. The roadmap
3. The sprint system
4. IRC and the mailing lists
5. API
6. Installation

Data wranglers

1. CKAN 1-page overview for wranglers.
2. POssiby installation belongs here (see below)
3. Two levels of dev -- light hacker and core hacker
4. Light hacker would be interested in tasks listed here: http://wiki.ckan.net/Extending_CKAN -- this is probably the most important bit of the docs
5. Roadmap for where we want to go http://trac.ckan.org/roadmap
6. Encourage them to upload new, derivative datasets -- check if there are machine tags etc for this (Richard/Rufus/ckan-discuss)

7. API: bring together existing resources. Note I think probably the most important one is http://packages.python.org/ckan/api/version2.html but it’s hard to find.

Publishers

1. CKAN 1-page overview

Administrator's Guide (including install)

1. start with various resources on http://wiki.ckan.net/Main_Page
2. see also one produced by client at http://www.datagm.org.uk/resources
3. installation guide is a tricky one. we have apt-based installation process which is only guaranteed to work with Lucid (should we make a downloadable virtual machine available for this?). otherwise people need to follow “developers install” which is quite involved. a lot of it has been scripted though -- ask James Gardner -- I think on balance probably we need three things (1) downloadable VM (could this be provided as part of buildbot process -- discuss with David Read) (2) well edited, practised and tested apt version: (3) ditto for developer version. with clear intro explaining choices and why you might make them
4. Cover common configuration options http://packages.python.org/ckan/configuration.html
5. for user's guide, consider best format: screenshots; integrated help in app; screencasts?
6. HOW TO UPGRADE SAFELY

Curators

1. How groups work
2. How tags work
3. Special tags for different subjects (I don’t know much about this -- but I think there are various things like machine tags etc -- ask Richard Cyganiak, Rufus, Jonathan and/or ckan-discuss list)
4. Collaborating with others (mention ckan-discuss...)