[OPEN-ILS-DOCUMENTATION] Documentation updates

[Jason Etheridge]

On Wed, Aug 11, 2010 at 2:28 PM, Karen Collier <kcollier at kent.lib.md.us> wrote:
> I'm a bit leery of mixing attribution within the main body of the documentation.  It could get pretty unwieldy if we're putting attribution statements on every page, and how do you decide which pages warrant their own attribution statement and which don't?  Particularly after all the "adding, mashing, mixing, remixing, revising, editing, etc" that Robert refers to it could become a real mess.

We could rely on revision control to track fine grained
ownership/credit, and keep a centralized contributors list separately.
 So for example, if you include a paragraph from source B into main
document A, the "changelog" or commit message for when you add the
paragraph to the repository can mention the source, and that
information would be there whenever someone reviewed the revision
history.  Alternately, docbook is XML, right?  You could embed an XML
comment <!-- like so --> into the document with the information.  It
wouldn't show up in the rendered output, but would exist for those who
know where to look.

So the idea is, you could keep the fine-grained information somewhere
for troubleshooting, legal questions, etc., but not have it clutter up
"presentation".

-- 
Jason Etheridge
 | VP, Tactical Development
 | Equinox Software, Inc. / Your Library's Guide to Open Source
 | phone:  1-877-OPEN-ILS (673-6457)
 | email:  jason at esilibrary.com
 | web:  http://www.esilibrary.com