evergreen-documentation-collage

Building our collage: how Evergreen’s documentation works

Title slide

• Collage: “Today’s progress on Circle” by John LeMasney
• Building our collage: how Evergreen’s documentation works
• Jane Sandberg, Linn-Benton Community College

Session plan

• Collage: “National Geographic collage - Air” by Bec Bigg-Wither
• Human processes behind Evergreen’s manual
  • How to contribute content
  • Potential process improvements
• Evergreen’s documentation ecosystem beyond the manual
• Interactive session
• Pause on each slide to enjoy the collage!

Four types of documentation

• Collage: “Collage” by Andrew Gustar
• Evergreen manual
• Contextual help
• Release notes
• Documentation for developers

Steps to add to the manual

• Collage: “Trout collage” by Faith
  1. Contributors identify and report a gap
  2. Contributors create or compile documentation
  3. Contributors submit documentation
  4. Docs Committers review and incorporate submissions

Step 1: Contributors identify and report a gap

• Collage: “Collage” by Lauren M.
• New features without documentation are listed on the wiki
• Gaps are sometimes also reported on Launchpad with the “documentation” tag
• Potential process improvement: publicize a lower-barrier way to report gaps

Activity 1

• Collage: “Collage” by Lynn Willis
• Team 1
  • Think of something that has confused you or others about Evergreen
  • Search the manual to confirm it is a gap
  • Once you have confirmed a gap, put it in the chat
  • Enjoy the collage
• Team 2
  • Enjoy the collage
  • Find a gap in the chat
  • Write a chat message to let others know you are taking that gap
  • Add the gap to the wiki or launchpad

Step 2: Contributors create or compile documentation

• Collage: “Collage” by João Tito Basto
• May be sourced from
  • Local documentation
  • Release notes
  • Conversations in emails, launchpad, IRC
  • New documentation
• Process improvements
  • solid procedures for attribution when we incorporate other docs
  • make it easy for others to remix the manual

Activity 2

• Collage: “Collage” by Gary Lund
• Find some Evergreen documentation online from a source other than the official manual
• Identify the license, if available, for that documentation
• In the chat, post a link to the documentation and what you found out about its license

Step 3: Contributors submit documentation

• Collage: “shoe Repaire in the TwiLight zOne” by Martin
• Submit any format to the Evergreen email list
• Submit AsciiDoc as a Github Pull Request - procedures available in the Evergreen manual

Activity 3 (optional)

• Collage: “Collage” street art by Murmure – Artisme, photo by Jeanne Menjoulet
• Sign up for the Evergreen documentation email list
• Create a Github Account and create your own fork of Evergreen

Step 4: Docs Committers review and incorporate submissions

• Collage: “eye garden” by Tyler Hewitt
• Process improvements:
  • Add more docs committers
  • Automatically generate a preview version of the documentation when a pull request is opened

Questions?

• Collage: “collage PC with bonus RAK” by Tricia J

Contextual help

• Collage: “walkabout” by Jill Allyn Stafford.
• Mini-documentation in Evergreen screens at the point of need
• One way to do this in the staff client is the component

Activity 4

• Collage: “Collage exchange” by May
• Together, let’s identify a screen in Evergreen staff client that could benefit from a help popover
• Together, let’s figure out the details of placement and wording
• We will then submit the request to launchpad

Release notes

• Collage: “Momentos” by Nico Sagredo.
• For new features, provided in the code
• For bug fixes, the release team creates brief notes

Developer documentation

• Collage: “Collage riffs” by jane cornwell
• Developers need both conceptual and just-in-time documentation too
• Shout out to Dan Wells, Remington Steed, Terran McCanna, and the New Developers Group

Questions? And thank you!

• Collage: “Collage #4” by BB