[ckan-dev] Remaining documentation issues for CKAN 2.0

Thu Apr 18 10:39:27 UTC 2013

> Yes this is part one of the docs refresh we will need to do another round
> in 2.1
> Also we need to get better on updating docs as we go not leaving them till
> later
> So we get feature + tests + docs = job done

Yeah, I'm thinking maybe we shouldn't write the docs last as it always
seems a bit tagged-on and easy to neglect. It's probably up to the
individual devs how they go about implementing a feature and different
people will do it different ways, but as a suggestion what might work
well is to try and get a "complete" first draft of the docs for a
feature (as complete as they can be) _before_ starting to implement the
feature. Do it in an actual rst file in the actual pull request. Then as
you implement the feature, flesh out and update the docs as you go along
as necessary, give them a final check and polish once the implementation
is complete, and merge. This could also get PMs and clients involved
early on as they can review the docs and say if they want the behaviour
changed.

In this way the docs would play a bit of the role that we currently try
to get from user stories and specs, they'd act as a specification for
the feature that is to be implemented.

But the docs wouldn't be the whole story for a feature -- there are
probably specific details of how it works and how it's implemented in
code, that don't really belong in the docs, so we may still need some
sort of additional spec or user stories during development. These could
just go on a wiki page, or in the pull request description and comments,
ckan-dev thread, all in the programmer's head, etc.

I think writing tests for a feature before/during implementation of the
feature, could also help in a similar way.