[OPEN-ILS-DOCUMENTATION] documented developmnt

[Dan Scott]

On Tue, Feb 08, 2011 at 03:20:35PM -0500, Grace Dunbar wrote:
>   Hi Robert (and everyone),
> I'll jump in a bit from the perspective of Equinox and hopefully we can 
> find a great solution for everyone.

Let's step back and remember what Robert actually asked:

> >   It would seem that these new features would have something written somewhere -- even rough notes? Is there an economic or contractual  reason why these cannot be shared with the general Evergreen community at an earlier stage by either the developers of the features, users of the new features or trainers for the new features?

Robert was asking for "something written somewhere -- even rough notes",
not the final product of commit-ready highly polished DocBook
documentation.

> I think we have two sides of the equation; contracted development with a 
> company like Equinox, or community development.  Obviously, the solution 

Ideally, contracted development should be community development. And for
the most part, that's what has been happening with the code: for much of
the acquisitions work, for example, Bill and Lebbeous committed their
code in progress as it was developed to the public Evergreen repository;
it didn't land in great big hunks.

> we come up with has to have a standard that fits both groups.  And I 
> believe that there is a common point at which both kinds of development 
> meet - at the commit stage.  Working backwards, perhaps the core 
> developers need to informally adopt the stance that no code is committed 
> without some kind of documentation.  But, of course, that is where it 
> gets tricky.  If the commit is a fix to some bug that only manifests 

It's tricky because we're currently committing everything to trunk as it
is developed. We've been discussing the possibility of changing our
development tools and methodology to make use of 'feature branches',
where specific features could be developed, tested, and stabilized before
getting added into the master repository. Adding 'documented' as one
more verb to that approach makes some sense I think.

> itself in a random database level error but doesn't display to the user 
> and doesn't affect performance, how much documentation does that get?  

A bug fix should get a commit message and possibly a release note entry
of its own if it's a fix for a bug in a previous release, and not just a
fix for a regression. We don't really have a standardized format for
release notes, which would be a Good Thing(TM) to have some time. But
that's another topic.

> Is documentation only for features with User Interfaces through the 
> staff client or OPAC?  Just thinking about it gives me a headache - I'll 
> let DIG and the developers haggle on that.

Systems documentation generally also includes concepts, tasks, and
reference material for installation, system administration, and
development.  I think DIG has done a pretty good job of covering that in
their outlines. (Kudos DIG!)

> Why aren't vendors providing documentation automatically?  Historically, 
> Equinox has provided many of our clients the option of paying for the 
> end-user documentation of the features we're creating.  Almost every 

I'm not sure it's realistic to expect every developer shop to offer
high quality documentation as one of its services. That said, the party
that enters into the contract has to have somehow communicated what it
wants from the developer shop. What I had suggested (perhaps clumsily)
during the DIG meeting was that at the very least the requirements docs
that framed the terms of the development contract should be readily
available for use as raw materials for DIG, as well as for fellow
developers who might want to understand what the expectations are for
this new set of features. Communications between the client and
developer shop on refining the requirements would be pure gold as well,
but this becomes capital H Harder... unless perhaps the original
requirements docs get annotated along the way. Which would be a good
thing for both the client and developer shop to do for their own sanity.

In the case of acquisitions, I know the KCLS requirements had been set
out to a fine degree of precision very early on - but these must have
changed. Only the original requirements at http://oss4pl.org/ are
available; maybe somebody can contact Lisa Hill (?) or Matt Carlson at
KCLS to see if anything more up to date is available.

> single one of our clients has declined this option.  We generally don't 
> produce end-user documentation for ourselves internally, so the 

Maybe your clients aren't convinced that Equinox has professional
writers on staff? I'm not saying that you don't (I honestly have no
idea), but that's another reason why a client would not want to pay for
a service from a given company.

> documentation goes unwritten. However, we have recently made a decision 
> to include documentation in all development contracts - it is no longer 
> an option.  We feel the clients and the community will benefit greatly 

Alternately, rather than requiring Equinox to have professional
technical writers on staff, perhaps the community should simply insist
that any new features that don't have sufficient documentation (and
tests, but that's the subject for a different discussion list) need to
stay out of the official release until such time as adequate
documentation is available. I think it's reasonable for a company to
offer services in a particular area of expertise, without having to try
to cover all bases.

That would give, say, Kathy Lussier's group the option of contracting
for the development of a new feature they want added to Evergreen, and
writing the documentation for it themselves (they have to come up with
the requirements documents anyway, and they need to sign off on what has
been developed, so they're arguably in the best position to document
their workflows according to the emerging design at the same time as
they're testing the code that is being developed to satisfy their
needs).

> from this moving forward.  We generally can't provide documentation any 
> earlier than after the code has been officially released in a specific 
> version of Evergreen.  Generally, this isn't due to any contractual 
> issues (although I think that the group paying for the work does have a 
> right to vet the documents first), it's simply because things change, 

The group paying for the work has the right to keep both the code and
documentation to themselves, for that matter. But I'm generally
optimistic that most sites contracting for Evergreen development want to
see their contributions in the official version of Evergreen. My
suggestion is to treat the documentation like code: get it out there and
write in the open, starting from stubs and outlines, right alongside the
code (maybe even in the same repository as the code). Yes, things
change, but documentation can change with it.

(Hey, I belatedly realized that DIG's documentation repo is a case in
point of openly developed iterative documentation - to date it has, by
necessity, been written after the features have been developed, but it's
not far-fetched to imagine a time when it will catch up - or for new
features to be documented as they're developed in the DIG repo. Maybe if
Evergreen moves to git as well, we can have one big happy community repo
again!)

> sometimes right up until the last minute.  Development is planned out in 
> general and the specifics of how a screen is laid out or what's in a 
> dropdown menu are often the very last things to be finalized.  Sometimes 

Change is good! 

SIDETRACK:

If your primary concerns are about having to update the documentation
because the screen layout changed, then either the UI needs to be
redesigned, or you're focusing on documenting the wrong things. I say
this as someone who is guilty of creating plenty of bad user interfaces
(I try to stay out of that line of work, but people seem to like
pointy-clicky things!) and who has written a ton of reasonable technical
documentation. The trick is to be able to describe the concepts clearly
("So, serials are composed of the following elements: distributions,
which are X and interact with libraries like so; streams, which are Y;
subscriptions, which are Z; issuances, which are FOO") and then list the
tasks and the corresponding places in which those tasks are
accomplished.