[Evergreen-dev] Ship Evergreen with a prebuilt manual?

Tue Sep 8 15:49:10 EDT 2020

I like this idea, it would be a good way for those that never see the documentation to actually use the documentation.

As we are in the process of migration, we are looking at updating our docs, and what all hast to go into the docs.

This will also force the Documentation Group to be more proactive in adding documentation,  this would also depend on the developers to add the necessary documentation to when a feature or Wishlist is added especially.

-----------------------------
Lynn Floyd
MIS Supervisor
Indiana State Library
317-232-3290
lfloyd1 at library.in.gov<mailto:lfloyd1 at library.in.gov>

From: Evergreen-dev <evergreen-dev-bounces at list.evergreen-ils.org> On Behalf Of Blake Henderson
Sent: Tuesday, September 8, 2020 12:59 PM
To: evergreen-dev at list.evergreen-ils.org
Subject: Re: [Evergreen-dev] Ship Evergreen with a prebuilt manual?

**** This is an EXTERNAL email. Exercise caution. DO NOT open attachments or click links from unknown senders or unexpected email. ****
________________________________
Galen,

I was thinking along those same lines: give our users (library staff) documentation references for each staff UI - making it eas(ier) for folks to resolve questions they may have about the Evergreen staff client. I think this would be a boon to the Evergreen project as a whole and might* make users morph into DIG members!

This statement couldn't be more true: "Any project is only as good as it's documentation."

I believe you mentioned that Koha does this? Where there is a "consortium" level document for any given interface, and it can be overridden all the way down the org tree?

So - I am for* the general idea. Exactly how* might require everyone's input.

-Blake-

Conducting Magic

Can consume data in any format

MOBIUS

On 9/8/2020 11:27 AM, Galen Charlton wrote:
Hi,

To propose an idea for discussion, the Antora work gives us an opportunity for us to (re)consider shipping a pre-built Antora site with each release of Evergreen. Pre-built documentation could be made available via (say) https://the.evergreen.server/docs/.

Some pros I see are:

* This would make it possible for the manual to be completely self-contained.
* Being able to count on /docs/ being available could inspire the creation of more context-sensitive help.
* /docs/ could more easily remain in sync with the version of Evergreen that's currently installed.
* Sites that wish to customize their documentation but are not writing it from scratch (or rewriting it wholesale) would be able to do so. Admittedly, that was already possible, but having more of the documentation site-building scripts in Evergreen itself makes a difference.

Some cons include:

* This would add about 45M to the uncompressed size of the Evergreen tarball. Not huge, but not nothing.
* Managing customized documentation that's built into an Antora site would have a learning curve.
* Built-in documentation could make certain features that consortium administrators have intentionally turned off a bit more visible than may be desired.

If we do this, I imagine we'd need at least library settings to control whether built-in documentation or externally-managed documentation is linked to from the staff interface. I could also imagine wanting to make access to /docs/ controlled by a staff permission.

Thoughts? I should note that I'm _not_ proposing that we try to do this for 3.6.0.

Regards,

Galen
--
Galen Charlton
Implementation and Services Manager
Equinox Open Library Initiative
phone:  1-877-OPEN-ILS (673-6457)
email:  gmc at equinoxInitiative.org<mailto:gmc at equinoxInitiative.org>
web:  https://equinoxInitiative.org<https://protect2.fireeye.com/v1/url?k=1c2e60c8-429efdd2-1c2a29c8-8697e44c76c2-cea0df9e1155c326&q=1&e=af492967-5bfe-4d0f-8bd8-c795745f68ff&u=https%3A%2F%2Fequinoxinitiative.org%2F>
direct: +1 770-709-5581
cell:   +1 404-984-4366

_______________________________________________

Evergreen-dev mailing list

Evergreen-dev at list.evergreen-ils.org<mailto:Evergreen-dev at list.evergreen-ils.org>

http://list.evergreen-ils.org/cgi-bin/mailman/listinfo/evergreen-dev<https://protect2.fireeye.com/v1/url?k=66097302-38b9ee18-660d3a02-8697e44c76c2-6c4efe84f854794a&q=1&e=af492967-5bfe-4d0f-8bd8-c795745f68ff&u=http%3A%2F%2Flist.evergreen-ils.org%2Fcgi-bin%2Fmailman%2Flistinfo%2Fevergreen-dev>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.evergreen-ils.org/pipermail/evergreen-dev/attachments/20200908/d99b46d2/attachment-0001.html>