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

[Galen Charlton]

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
web:  https://equinoxInitiative.org
direct: +1 770-709-5581
cell:   +1 404-984-4366
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.evergreen-ils.org/pipermail/evergreen-dev/attachments/20200908/2ee63477/attachment.html>