User Tools

Site Tools


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
  • Also used for Fedora Documentation: https://docs.fedoraproject.org/en-US/fedora/f29/
  • 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: 2019/04/27 07:48 by sandbergja

© 2008-2017 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a member of Software Freedom Conservancy.