Decide on what gets put where, and how

[MattBlissett]

The Asciidoc experiment is a two-line Jenkins build, so there's probably not much overhead for Informatics. This helps us compare other free/commercial services. I had thought they were offering a lot more, but there are probably still some features that wouldn't be worth our time to implement, like print colour profiles.

Decisions:

• Target format(s) : HTML, single page HTML, PDF, ePUB etc
• Free, paid-for or GBIF-run build (i.e. GBIF Jenkins, Gitbook, electric books etc)
• Final destination of HTML/PDF (e.g. building with GH Pages forces hosting by Github, some services include hosting, affected by...)
• How much to integrate with the portal

I suggest:

• Adding an Asciidoc stylesheet for both PDF and HTML (or for hosted services, seeing how to restyle things).
• Testing multi-page HTML, if that might be needed
• Testing a translation
• Testing adding images like screenshots

[MattBlissett]

With a basic service like Gitbooks

• "+" Zero or almost zero time from informatics
• "–" Limited control of style
• "±" Potential for confusion from contributors? (Github, Gitbooks, git-what?)

With a service like Electric Book Works:

• "+" Zero or almost zero time from informatics
• "+" (Seemingly) lots of control of style
• "–" Expensive?

Self-hosted:

• "±" Small time from informatics for building + hosting (could also just show Laura)
• "+" Full control of style
• "–" Potentially time needed if complex custom styling is required (could end up re-implementing features of the services).
• "+" Can have a test environment

[kcopas]

Thanks, Matt—it was great to have you available to weigh and test all this in real-time.

Note that neither Gitbooks nor Electric Books Works use Asciidoc: the former was an initial experiment of mine, and the well-documented workflow attracted my attention to the latter.

We need to investigate other Asciidoc service providers to have viable, non-self-hosted options—like OpenDevise. They maintain Asciidoc and also produce Antora, which looks very much like the kind of tool we might want.

[kcopas]

Closing in favour of open issue #13 on the last unresolved item here: 'how much to integrate with the portal'.

Current thought is that this will be done through card-based 'features' on a planned landing page template for the site's documents. Curated access to individual docs (and even potentially sets of docs).