[OPEN-ILS-DOCUMENTATION] documented developmnt

[Grace Dunbar]

  On 2/8/11 11:23 PM, Dan Scott wrote:
Dan,
For brevity, I'm leaving out all the things that we agree completely 
on.  ;-)
>> 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.
Well, of course!  When we are working on our contracted development we 
commit early and often to trunk and welcome feedback from the 
development community.  My distinction was that whatever process and 
standards the community would have of the developers needs to be applied 
to all developers including those who are not working for a vendor.
>> 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.
I actually think every development shop *should* offer documentation.  
No offense to developers but the way many of you think (and name things) 
and the way librarians think can cause some confusion.  Even basic 
documentation is better than nothing (obviously).
> That said, the party that enters into the contract has to have somehow communicated what it
> wants from the developer shop.
Indeed.  Basic blueprints and desired use/outcome.
> 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.
Great example!  The KCLS requirements for Circulation, for example, were 
set forth with a high degree of specificity.  However, as we worked 
through the development and provided proof of concepts or rough 
interfaces, things changed.   Those things were identified and noted as 
the project moved forward in TRAC.  The TRAC notes have a lot of private 
dialogue and shorthand between the project managers, the client, and the 
developers.  Those notes simply aren't fit for community dissemination 
but they're all we have.  And, of course, after 8 or 16 months, some of 
the notes that were made are cryptic at best.  I'm not sure if KCLS kept 
a changelog of their requirements on their end, I suspect they may have 
been too busy to do so.
> 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.
Our Professional Education Manager, Sally Fortin, has been writing our 
documentation for over a year and has been contributing  everything she 
has written to the community at the time the development was delivered 
to the client (usually before it was included in a release).  I can 
think of two examples of her work off the top of my head.
http://docs.evergreen-ils.org/1.6/draft/html/actiontriggers.html
http://docs.evergreen-ils.org/1.6/draft/html/admin-booking.html

> 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 understand what you're saying but I don't think that what you've 
described is moving us toward the building blocks of a process.  I think 
that the community and all of it's stakeholders can and should agree to 
a basic standard for brief documentation that must accompany all new 
features.
For example:
-list of required permissions and descriptions
-basic description of intended use cases
-basic outline of intended order of steps
-brief description of UI layout and features
-known issues

> 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).
I think a distinction should be made here between documenting workflows 
and documenting functionality.  Take the Booking Module, for example. 
Mohawk graciously went ahead and expanded their development to include 
the ability to create "resources" like rooms or laptops, so that 
libraries could create and reserve those things for patrons.  This 
wasn't something that Mohawk intended to use - they mainly wanted the 
ability to reserve books/dvds for academic staff.  For example, a 
professor wants to show a dvd in class on May 22 and she reserves it 
ahead of time to ensure it is available to her at that time.  So how 
Mohawk uses their development (Mohawk's workflow) isn't going to 
necessarily be good documentation of the functionality.  The same thing 
applies to Acquisitions and Serials.  There are many ways to approach 
acquisitions and serials - start from a PO, start from a selection list, 
start from a cart at Ingram; do you barcode your serial issues, do you 
bind your serial issues, do you process items centrally or at the 
branches? (and on and on)

That is all workflow, policy and procedure and it is all going to be 
different from place to place.  I think the job of the community and DIG 
should be to try to document the features in their entirety (probably 
including some sample workflows for reference) and let local 
institutions make use of that work to modify it to their local needs.  
Because it the development is being done out in the open by the whole 
community then the code really isn't being developed to satisfy their 
needs - it's being developed to satisfy *a* need and should be made 
flexible enough to accommodate multiple needs (aka workflows).

> 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.
That sounds great and if that's what DIG wants then I'm game to try it 
out. I must say though that I'm afraid that process might just end up 
being extra work.  We have had experience writing documentation for 
several projects both small and large.  In our experience, it simply 
wasn't effective to try to write any documentation until the project was 
in the testing phase because too many things change.
> Change is good!
It is - but not when you end up re-writing something 5 times.
> 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.
Despite what your innuendo would indicate, I never stated that I had 
concerns about updating documentation.  I was just saying that, in my 
opinion, it wasn't an efficient workflow.
>   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.
>
>  From there, documenting how to perform a task on a given screen should
> be close to mechanical. ("Step 1. In the Foo panel, select the target
> library from the Bar widget. The Frambazzle dialog opens.... Step 2...")
This is a fallacy of composition - if I have all the concepts of the 
development outlined and described then the development is clear and 
documentation practically writes itself.

Writing good, useful documentation isn't about describing the 
components.  And, in the course of community development, those 
components often change, which is the point I'm trying to make.  The 
overall end result doesn't change (ordering items via EDI from Baker and 
Taylor) but steps, processes, names, etc. *do* change.  Why?  Because 
we're doing community development and things change based on feedback.

However, providing the outline and basic structures for feedback from 
the community during development is useful for development - but I don't 
think as useful for documentation.  And if the place where the outline 
and structure is available to the community is updated with changes and 
progress, then that becomes VERY useful when the time comes to document 
the feature.
> A colleague of mine used to say "If the UI's a dog, the help will bark."
> If the help is barking early on in the documentation process, that might
> be early enough to suggest that some change would be good. If the
> documentation is held off until the end, though, then that's a missed
> opportunity for feedback.
I disagree.  There are ways to update the path of development which 
allows for feedback without creating documentation- see above.  Creating 
documentation before the development is close to being finished is 
putting the cart before the horse.  I don't write a summary of my summer 
reading program's success on the second week of the program, I wait 
until the last week.   But I do make notes and update my data along the 
way...
> Now, getting the documentation out at the time of release?  That should
> be an achievable goal for Equinox; however, I can't speak for the
> community developers - and all the developers should be held to the same
> standard.  Since there isn't a "client" who is commissioning the work,
> perhaps the community developers could use DIG as they go along their
> development path to provide testing and documentation.

> I hope that Equinox doesn't see itself as being separate from DIG or
> community development. Crazy idea: if part of the release standard was
> "no new feature goes into the official release without adequate
> documentation" and DIG was the arbiter of what "adequate" meant, then it
> would be a level playing field for all.
Dan, I'm sorry if my comments weren't clear.  Let me reiterate: Equinox 
has the in-house tools to provide basic documentation for every 
development project they are undertaking going forward.  We believe we 
owe that to the community.  The other developers in the community 
(vendor or non-vendor) will need a mechanism for providing documentation 
with their development.  I think if the community agrees that DIG should 
be the arbiter of what development goes into a release based on 
documentation we should at least agree on a basic well-defined standard.

> Keeping features out of an official release due to a lack of
> documentation may be a crazy idea, yes. But a boy can dream. I think
> these (who decides what's in an official release? Hey, should the docs
> be part of the release tarball? Or at least offered for download as a
> separate tarball?) are very healthy discussions to have. Development is
> development, whether it's paid for via a contract, or paid for via a
> salaried position, or paid for via somebody's volunteer time when their
> kids are asleep and they could be doing 1000 other things. Documentation
> is exactly the same, and is arguably as valuable as the code underlying
> the features it explains.
>
I don't think anybody is arguing that documentation is important.  And 
the discussion of how to handle the documentation aspect of Evergreen 
development is past due.  I will be the first person to admit that we 
regret not being able to provide excellent documentation for every 
feature we've worked on.  We really are committed to working with 
everyone in the community to resolve this in a way that makes sense.

Thanks for the spirited debate!
Grace

-- 
Grace Dunbar
COO
Equinox Software, Inc.
gdunbar at esilibrary.com
1-877-OPEN-ILS  x5579
www.esilibrary.com