Skip to content

Latest commit

 

History

History
64 lines (50 loc) · 3.89 KB

18-11-20.md

File metadata and controls

64 lines (50 loc) · 3.89 KB

Documentation Interest Group — November 18, 2020 — 11:00 AM Eastern

Zoom: https://us02web.zoom.us/j/87888134747

  • Chair: Mirko Hanke

  • Notes: Melissa Anez

  • Attending:

  • Mirko Hanke

  • Melissa Anez 🌠

  • Rosie Le Faive

  • Danny Lamb

  • Julia Corrin

  • Amy Blau

  • Yamil Suarez

  • Cary Gordon

  • Don Richards

Resources:

Agenda:

  • New documentatin structure is live
  • Open pull requests
  • How to document how to make GitHub issues, and make that much easier to discover?
  • ISLE docs (ISLE sprint hapening now)
  • New workflow for editing documentation
  • CLA for documentation contributors

Future discussion topics (timing TBD)

  • Accessibility
  • Workflow: Ensure users can provide feedback or suggest edits
  • Cooperation with Lyrasis around IMLS grant for Fedora migration

Notes

  • New docs structure includes some placeholder pages so that we have a reference for where we need to build up more documentation. There are many gaps identified in Rosie's structural doc that can be worked into this. We need a shared space to track that discussion, and will keep trying to categorize documentation, either my audience or by other criteria. Are there ways to modularize information? Not just classifying pages, but classifying pieces of information on pages. Mkdocs may allow for includes, but this is a complex tool for the kind of work we're doing.
  • How do we get more people to write docs?
    • Spreadsheets and signs up have worked well when tied to a release or a sprint. Identify what we need done, ask folks to sign up for individual tasks
    • Dedicated training sessions on how we do docs has worked well in other open source
    • Maybe a combo of both: regular docs sprints, with a spreadsheets, opened with a training session each time
  • Can we add a footer encouraging users to make Issues when they identify a gap or a bug? We're looking into GitHub Issue template to add some gentle guidance. How-to videos for making issues would be helpful. Melissa will put this on her to-do list.
  • Pull requests:
    • Islandora/documentation#1692 you have to open each menu link to find tabes of contents. This hides some pretty key user docs, so this pulls tries to surface them a little more.
  • Live demo of merging pull request #1699. It's quick and easy and anyone who is a member of our github org can do it! You do not need ot be a committer to review and merge documentation in Islandora.
  • ISLE sprint is nearly done, but there's more to document. Maybe humanizing the readme? Danny is writing some docs on his experience using isle for the Islandora online sandbox, but could use reviewers when it's ready.
    • What is the relationship between readmes and docs? What information goes where?
    • Can this group set some guidelines?
    • How do we close the loop on getting docs finished when adding new features? The skillsets for docs versus development are often different. We've talked about having new features demoed at the user call. maybe buddy up a programmer with a docs writer? We lose programmer by-in once things are merged and they can move on to other tasks, which is a challenge.

Action items:

  • Cary to work on getting a footer added to the docs to encourage making issues
  • Melissa to make simple how-to videos for creating issues
  • All: research other mkdocs themes we could switch to