[OPEN-ILS-DOCUMENTATION] Circ docs (Re: Introductory Material for the Book of Evergreen)

[Soulliere, Robert]

Thanks Steve.

I've been leaving images out of the documents I've been converting for now, and editing accordingly. I will add them later or give other DIG members a chance to add them as needed or desired. You brought up a couple of issues with images which present several challenges to documentation.

1) Issues with sizing for PDF documents -- large enough to read, small enough to fit in the limited width of the page. We can probably set some definitive parameters for image size, but some of the images in the word docs we are converting may be too large for PDF files. I would either leave them out or create new screen shots if possible and necessary.

2) Translations -- It creates more work to translate since translations of the documentation will need screen shots in their language.

3) Updates and customizations -- Evergreen provides a couple of skins out of the box with very different looks.  Folks can customize their skins so the screen shots may look very foreign for those using the alternative skins. Moreover, the standard skins will change over time. It will be much easier to update the documentation for later versions of Evergreen with minimal screen shots.

If the image is specific to an organization and not the default out-of-the-box Evergreen version, I would leave it out. You could either use a text alternative like you suggested in some cases,  add a placeholder of some kind to add image later, or replace if you think it is critical.

Personally, I am a screen shot minimalist given the challenges above. If text can be a adequate alternative and screen shots are not required, I would use text. Of course, this has lots to do with learning styles and there may be differing opinions on this topic. Moreover,  some images are truly essential to the content.

Thanks,
Robert




________________________________________
From: open-ils-documentation-bounces at list.georgialibraries.org [open-ils-documentation-bounces at list.georgialibraries.org] On Behalf Of steve sheppard [ssheps at gmail.com]
Sent: August 4, 2010 12:04 PM
To: open-ils-documentation at list.georgialibraries.org
Subject: [OPEN-ILS-DOCUMENTATION] Circ docs (Re: Introductory Material for      the Book of Evergreen)

Robert, all,
I worked on a handful of Lindsay's docs, converted  them  to DocBook format, then added them to the GitHub doc repository. This is just a first pass; no doubt they still need polishing.
Will review and expand as I get time.

Had issues with the 'Login' document -- I converted a couple of images (a right-arrow, an info logo near the bottom of the original), but they don't look quite right in the final PDF; but might look better if just replaced with simple bullets.
But more importantly, the image of the actual login page is specific to the OWWL / Pioneer Library System.

In general, should we keep specific images like this, but just label them appropriately (e.g., "Here are examples of ...") ?
Or should we remove proprietary logos and names completely, or maybe replace with some generic equivalent?

Me, I'm for leaving images as-is but adding "...example of..." comments.
What do you think?

--Steve


This E-mail contains privileged and confidential information intended
only for the individual or entity named in the message.  If the reader
of this message is not the intended recipient, or the agent responsible
to deliver it to the intended recipient, you are hereby notified that
any review, dissemination, distribution or copying of this communication
is prohibited.  If this communication was received in error, please
notify the sender by reply E-mail immediately, and delete and destroy
the original message.