[ckan-dev] Remaining documentation issues for CKAN 2.0

Mon Apr 22 15:36:58 UTC 2013

On 18 April 2013 11:39, Sean Hammond <sean.hammond at okfn.org> wrote:

> > 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.
>

I like this idea and it would also be really useful if we had more clarity
on the intended behaviour of new features before we
start implementing them. As an alternative to writing lots of documentation
up front we could use acceptance criteria to quickly and concisely define
the intended behaviour.

http://agile-wiki.wikispaces.com/Drafting+Acceptance+Criteria

How about

* Product owner and the developer flesh out the acceptance criteria before
development starts.
* Acceptance criteria are included in the pull request as a skeleton for
the docs docs (Good acceptance criteria will at least tell people the
intended behaviour)
* Documentation is completed as the feature is implemented
* Documentation must be complete before pull request will be merged

>
> _______________________________________________
> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.okfn.org/pipermail/ckan-dev/attachments/20130422/9fdbee7e/attachment-0001.html>