Antora! Antora! Antora!
An Evergreen Documentation
Bombshell

Slides available at:
slides.mobiusconsortium.org/blake/antora

Created by Blake Graham-Henderson / [email protected]

Press ESC to browse slides

This presentation is about:


DOCUMENTATION!!!!

Specifically Evergreen Documentation

What IS documentation?


  • Mainly: words and sentences
  • Also: formatting
    • Headings, numbered lists, highlighting
  • Also: images
  • Also: navigation

How do humans write the documentation?

We can write a book.

  • Need editors
  • Need publisher
  • Need time to publish and distribute
  • The book will be out of date by the time this process is finished

How do humans write the documentation?

We can publish online.

  • Need editors
  • Need publisher
  • Need time to publish and distribute
  • The book will be out of date by the time this process is finished
  • Need to know HTML

How do humans write the documentation?

We can publish online with ASCIIDOC.

  • Need editors
  • Need to know HTML
  • Need to know ASCIIDOC

ASCIIDOC

  • Lowers the bar of entry
  • Attracts new editors because easy to learn
  • Reduces the keystrokes required

Simple

We need (mainly)
  • Words
  • ....and images

Words

Item Status

Deleting Item Statuses

1. Highlight the statuses you wish to delete. Ctrl-click
   to select more than one status.
2. Click Delete Selected.
3. Click OK to verify.

{image of the interface here}

NOTE
You will not be able to delete statuses if items currently
exist with that status.

Formatting

Item Status
<---- Heading 
Deleting Item Statuses
<---- Subheading 
1. Highlight the statuses you wish to delete.
   Ctrl-click to select more than one status.
2. Click Delete Selected.
3. Click OK to verify.
<---- List (numbered or bulleted) 
{image of the interface here}
<---- Picture file 
NOTE
You will not be able to delete statuses if items
currently exist with that status.
<---- That's a "note"

ASCIIDOC in Action

= Item Status =
<---- Heading 
== Deleting Item Statuses ==
<---- Subheading 
. Highlight the statuses you wish to delete.
   Ctrl-click to select more than one status.
. Click Delete Selected.
. Click OK to verify.
<---- List (numbered or bulleted)
Numbered: period "."
Bulleted: astricks "*"
image::media/copy_status_delete.png[Deleting item statuses]
<---- Picture file 
[NOTE] You will not be able to delete statuses 
if items currently exist with that status.
<---- That's a "note"

Results

Italics?

You might have noticed the italicized words

Italics - it's easy!

. Click _Delete Selected_.
. Click _OK_ to verify.
<---- wrapped in underscores

Big issue: organization

  • Where is everything?
  • How do I edit something?
  • How do I create something new?

Evergreen documentation

We put all of our docs into the Evergreen code repository

Evergreen repo /

Evergreen documentation

docs folder

docs /

46 items in this folder

Evergreen documentation

media folder

docs / media

1,344 items in this folder

Evergreen documentation

Evergreen repo / docs
Generated ---->

Admin Folder

docs / admin

Take a look at the product

The old (current) way:

Landing Page

Main Nav

Admin root - step one

Admin - step two

Where'd the nav go?

What is Antora?

  • Open Source
  • Generates the website from ASCIIDOC

From Antora's site:
The Static Site Generator for Tech Writers

Side by side

Navigation
Breadcrumbs
Search
Version

Anything different?

Well, yes. A little.
Antora enforces a folder structure.
And it's an improvement.

Folder structure

Root folder
Old root folder
docs /
Antora root folder
docs-antora /

Folder structure

Modules folder
Old
docs /
Antora
docs-antora / modules

Folder structure

Circulation folder
Old
docs / circulation
Antora circ folder
docs-antora / modules / circulation

Folder structure

Circulation folder
Old
docs / circulation
Antora pages folder
docs-antora / modules / circulation / pages

Folder structure

Circulation / media
Old
docs / media
Antora
docs-antora / modules / circulation / assets / images

Folder structure

Circulation / media / sub
Old
1,344 items
Antora
65 Items

Can be organized per doc

A word about images

  • Antora knows!
  • Small config file

                            :attachmentsdir: {moduledir}/assets/attachments
                            :examplesdir: {moduledir}/examples
                            :imagesdir: {moduledir}/assets/images
                            :partialsdir: {moduledir}/pages/_partials

A word about images

Now you can refer to an image like this:


                            image::media/holds_title_options.png

Add ALT text


                            [Place Holds screen with Basic Options]

Complete


                            image::media/holds_title_options.png[Place Holds screen with Basic Options]

More control over navigation

Divided Navigation

Main Navigation
antora.yml

                            name: docs
                            title: Evergreen docs
                            version: 'latest'
                            nav:
                            - modules/ROOT/nav.adoc
                            - modules/installation/nav.adoc
                            - modules/admin_initial_setup/nav.adoc
                            - modules/using_staff_client/nav.adoc
                            - modules/sys_admin/nav.adoc
                            - modules/local_admin/nav.adoc
                            - modules/acquisitions/nav.adoc
                            - modules/cataloging/nav.adoc
                            - modules/serials/nav.adoc
                            - modules/circulation/nav.adoc
                                .......

Circ Module Navigation

Circulation folder
modules / circulation / nav.adoc

                            * xref:circulation:introduction.adoc[Circulation]
                            ** xref:circulation:circulating_items_web_client.adoc[Circulating Items]
                            ** xref:circulation:basic_holds.adoc[Holds Management]
                            ** xref:circulation:booking.adoc[Booking Module]
                            ** xref:circulation:circulation_patron_records_web_client.adoc[Circulation - Patron Record]
                            ** xref:admin:patron_self_registration.adoc[Patron Self-Registration Administration]
                            ** xref:circulation:triggered_events.adoc[Triggered Events and Notices]
                            ** xref:circulation:offline_circ_webclient.adoc[Offline Circulation]
                            ** xref:circulation:self_check.adoc[Self Checkout]

Table of contents

Each page has a table of contents

Antora generates that magically based on subheading, sub-subheading, etc.

modules / circulation / pages /
circulating_items_web_client.adoc

                        = Circulating Items =
                        :toc:

                        Check Out
                        ~~~~~~~~~~

":toc:" is all you need to make the Table of Contents

Bonus

A nice ASCIIDOC editing tool. ASCIIDOCFX

Handy links

THE END

Blake Graham-Henderson

MOBIUS

[email protected]

Slides available at:
slides.mobiusconsortium.org/blake/antora

Launchpad bug: LP 1848524