evergreen-docs:dig_meetings:20190426-minutes
In-person meeting, April 26, 2019
Antora
Blake introduced us to Antora, which Mobius is using for their internal documentation
Ascii-doc based, and relies on git – good match for the tools we're already using
Produces
HTML documentation that behaves like a modern Web site, with persistent navigation on the left
Blake and Ted set this up for Mobius, and it looks stylish
Would allow us to create "Edit this page on Github" links that are specific to each page
-
We would likely need to change how we structure our files in the repository, and add some extra Antora-specific files
Future of the docs
How we see users using the docs 5 years from today
Search on tags, specificities
Not so many things on the screen at one time, make the UI less intimidating
Linked docs from within Evergreen, based on the specific function you're trying to do
Make it a quick reference
The documentation as the resource that front-line trainers use first, rather than creating their own manual
Better mobile interface (especially with those screenshots)
How-To videos embeded in the documentation
A lot more screenshots, visual aids help
More accommodating for different learning styles, especially visual and auditory learners
Be able to choose which version you're searching
Better index
Keep the glossary more up-to-date
An easier way to download small, manageable chunks for local use and editing, not just the whole big PDF
How we see contributors contributing to the docs in 5 years
Lowering the barrier to entry
Wiki-style "Edit this page" so you don't have to worry about git, github, keys, what a "pull request is", launchpad, email list, etc.
Languages and translation – will we someday be able to improve this with AI?
Version history - make it visible and easy to work with
Full peer-review
Make a central place to start contributing; don't make contributors need to have a million tabs open and understand what each one does
evergreen-docs/dig_meetings/20190426-minutes.txt · Last modified: 2022/02/10 13:34 (external edit)