[OPEN-ILS-DOCUMENTATION] documented developmnt

[Dan Scott]

On Wed, Feb 09, 2011 at 12:56:11PM -0500, Grace Dunbar wrote:
>   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.  ;-)

Yeesh. Still a lot left!

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

And the point I was attempting to make (this was just the setup, the
payoff came later) was that documentation should be written the same way
as the code is: committed as it is written to a public repository.

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

Agreed on the latter; on the former, it's a matter of scale. If a lone
contractor qualifies as a development shop, offering high quality
documentation may be a pretty high bar for a Python coding genius, and
would probably be the wrong use of their skills.

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

Which is a great start. In a weird coincidence, there's this thing on
http://launchpad.net/evergreen called "blueprints", unfortunately it
doesn't seem to be particularly useful or used for anything more than
pointing to the Evergreen wiki for specs. But the wiki is pretty darned
useful - a nice central searchable place, fairly low bar for updating,
collaborative... and has been used by DIG as a starting point for a
number of sections of documentation.

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

Well, I guess it's a good learning opportunity for KCLS, Equinox, and
the Evergreen community. What does everyone take away from that
experience and how do we avoid making the same mistakes again for the
next big project?

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

I do remember the action triggers document turning up on the DIG list
about a week after I had torn my hair out for a few days trying to
figure out how to make them work in practice, and posted my findings
(such as they were) to the list. Had a draft been posted a week or so
earlier, it would have saved me some grief - although I noticed that the
DIG adaptation of the documentation includes a number of useful
additions, possibly the result of combining some of my findings.
 
> > 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 

Umm... aren't we moving forward (whether it's towards building blocks,
or directly towards a process) by having this discussion at all?

> 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

So that's a step towards a definition of "adequate documentation",
right?

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

Yes, functionality (all the things you could possibly do) is broader
than workflows, but based on my experiences at IBM talking with
customers who worked with the documentation that my information
development department wrote, their priority was to answer the question
"How do I do X?". They didn't want to be told that there are 10
different ways you could do X, and here are all the different ways you
can configure the system to support those different ways, they wanted to
follow the beaten path as much as possible so that they could get their
jobs done as efficiently as possible and run into as few edge-case bugs
as possible.

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

True, not necessarily, but Mohawk's workflow would reflect how a real
live site is using it, which is gold. Sally did a nice job of breaking
out the task for the expanded functionality so that it is primarily just
one extra administration step (creating the bookable resources) and
flagging the task with a title that distinguishes it from the core
workflow. So... not sure what we're discussing here. Mohawk wanted
some functionality, including some expanded functionality, and Sally
documented their core workflow and the additional workflow that Mohawk
paid for (I imagine they had some input into that additional workflow?).
Kudos!

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

Many thanks to Lebbeous for writing the serials documentation that he
put in the wiki, and to both Lebbeous and Dan Wells for responding to
questions on the list where the docs didn't cover aspects.

For acquisitions, right now we have no documentation*, so everybody
starts at ground zero trying to figure out how to make things work, and
whether features are missing by design (are discounts possible? am I
supposed to be able to add an item to a PO after it has been created?)
by collaborating and sharing their experiences on the list, bumping
their heads into walls, and occasionally being getting advertisements
for training sessions in response. With the exception of the latter,
it's a healthy collaborative process that should be expected in the
absence of documentation.

But if there was even one documented workflow from start to finish, that
would provide a path for people to be able to test and know what is
expected behaviour and what is potentially a bug, and then expand that
path outwards with some of the variations to start defining other
workflows with known outcomes.

*Not completely true, as I found Joe Atzberger has placed some
low level EDI documentation and samples in Open-ILS/src/edi_translator
which should be quite helpful.

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

The testing phase? But now we have a continuous integration server,
we're testing every time there's a change to OpenSRF (and soon
Evergreen). Okay, that aside - yes, it can make sense to delay some
documentation writing until things are closer to completion. 

> > Change is good!
> It is - but not when you end up re-writing something 5 times.

Ah, maybe if I had worked in a tech writing environment where that
didn't happen more often than not I would have stayed there...

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

Didn't you just say that change is not good when you have to re-write
something 5 times?

Well, technical writing goes hand in hand with testing in many ways.