[OPEN-ILS-DEV] [OPEN-ILS-DOCUMENTATION] ***SPAM*** Re: ***SPAM*** Re: Forming Teams by Topic

[Jason Etheridge]

> Seems to me there is a need for someone on the Equinox side to work closely
> with the DIG to set up appropriate workspaces (or workflow) for submitting
> the documentation so it can be committed as appropriate (just like you would
> with code, right?).  I imagine the bulk of the documentation being developed
> will occur in the wild and then the DIG group would have one person
> responsible for working closely with ESI to ensure it is submitted to the
> right branch.

Replace "Equinox" with "Evergreen developers".  Equinox has the most
Evergreen developers at the moment, but we shouldn't equate Equinox
with Evergreen.  The community can find equally capable folks outside
of Equinox.  However, I can (and do volunteer to) field patches
related to documentation and documentation features (like
context-sensitive help), but I'd quickly push for letting such patch
submitters become commiters, since I'm a lazy developer. :-)  I also
don't want to take on the role of a documentation editor.  "Working
closely" in the open source world can include discussions like this in
public mailing lists, so I'm not particularly interested in any sort
of private huddling, and I don't have any particular insight here,
just opinions.  We're doing okay, just keep the momentum going.  Even
if someone were to massively fund Equinox or other Evergreen support
and development companies to  help out more with documentation, I
wouldn't want to see the volunteer and cosmopolitan nature of DIG
change.

> I'm more interested in working with the context sensitive help and any other
> documentation that lives inside the code.  I think a lot of the work being
> done by DIG so far has focused on documentation that may refer to a specific
> release but doesn't necessarily live inside the code.  Right?  And for that,
> I'm not sure it still makes sense to have THAT documentation follow the
> branches and bugfixes so closely...does it?  Seems like User and Admin
> Manuals could stay at the Major Release level, not?

It could, but if it were to exist within the same source repository,
all this versioning would happen essentially for free, and you might
spend less time trying to "synchronize" versions of the documentation
with versions of the source code.  A "bug-fix" version would get an
appropriate copy of the documentation, and documentation folks may not
have to concern themselves with it at all (the bug being "documented"
in a change log).  Or maybe not.  Robert's idea of annotating snippets
of content with version information is fine, and probably easier for
folks to understand and get started with.  I say do whatever is
easiest first, and then solve problems as needed as they occur.

Hopefully we won't have a proliferation of active major branches,
releases, etc. in any case, and whatever we do will be manageable.

As for the context-sensitive help, the functionality is there, so make
use of the local hooks it provides.  Focus on that for your immediate
needs, and then later, maybe donate all that content to DIG to use for
seeding stock help files (after an appropriate scrubbing of policy
specific information, etc.)  Or better, make it available all the time
under an open source license, so anyone interested could use and adapt
it, without waiting for official "releases" from you.  In time, you
may find yourself using the community maintained versions of these
files, with smaller and smaller customizations needed for your local
installation.

-- 
Jason Etheridge
 | VP, Tactical Development
 | Equinox Software, Inc. / The Evergreen Experts
 | phone:  1-877-OPEN-ILS (673-6457)
 | email:  jason at esilibrary.com
 | web:  http://www.esilibrary.com