Child pages
  • 2018-03-20 Meeting Agenda and Notes
Skip to end of metadata
Go to start of metadata


 11:00 AM EST at

 Click for additional ways to connect...

Topic: Samvera Documentation WG
Time: this is a recurring meeting Meet anytime

Join from PC, Mac, Linux, iOS or Android:

Or iPhone one-tap (US Toll):  +14086380968,703126880# or +16465588656,703126880#

Or Telephone:
    Dial: +1 408 638 0968 (US Toll) or +1 646 558 8656 (US Toll)
    Meeting ID: 703 126 880
    International numbers available:

Or an H.323/SIP room system:
    H.323: (US West) (US East) (China) (India) (EMEA) (Australia) (Hong Kong)
    Meeting ID: 703 126 880


Or Skype for Business (Lync):

Facilitator: Andrew Myers

Notetaker: Ryan Steans


Agenda / Notes:

  1. Roll call (please log in above)
  2. Review project board:
    1. Review outstanding PRs
    2. Reporting on items completed since last meeting
    3. Review status of in-process tickets
    4. Discuss ready items & groom backlog
      1. Any new items needed?
      2. What should be moved to ready?
  3. Other agenda:
    1. HTML Proofer... got it down to only 165 failures!
      1. Explore them? Fix them? Punt?
    2. Can someone remind me whether is for all of Samvera products, or just Hyrax?
      1. thoughts on a product-centric (and thus, a version-centric) organizational structure?
    3. Other documentation efforts
      1. What is our strategy for coordination?
      2. Do we need to be more vocal?
    4. Blog?
  4. Pick facilitator / notetaker for next time
    1. Notetaker is responsible to copy template agenda into a new agenda for next meeting and add any followup items immediately.


  1. Discussion re: project board items

Do some reviewing

Get things off PR list and pushed

Specifically - Lynette's Glossary - Already approved - feedback from JulieRudder - if no changes, can we push?  Consolidating terms into a usable glossary - Decision:  MERGED

Oldest one - Amending Documentation - subtracting an unordered list presumably to remove something no longer relevant  - issue on Hyrax for that  - It may be that LaRita needs to pick it up, HyRax issue tagged to this - Documentation is fine - update documentation and then tag the issue on it.  Will fix the issue and then update the documentation (push).  

PR 166 - Minor and version specific (Jen) - Hyrax server chatter about notification, make sure this is version specific (it is now).  Where you can set notification update.  Minor, but nice for anyone using Hyrax 1 as there's so much chatter. - Does not have new stuff in it - front matter to specify the version - line that this only applies to 1.0.  AI: Drew will work on this offline.

ReadMe has reference on how to add versioning

184 -   haven't looked at it in a bit.  Added editor's chages.  ACTOR stack is complicated.  Jen is taking a look at it - not where we'd want it to be.  Need to update it with the Tech Writer's stuff.  

Justin has provided some description of the Actor Stack - 

QUESTION:  Should we frame our Interviews as a Blog Post?  Jen considering it - the interview itself - how do you control flow when in stack?  Why would you want to use a transaction?  when in process of saving work and do derivatives - didn't quite get it.  Material just wasn't quite there.  Original interview.  Decent enough, better than nothing.  Could get ahold of an Actor Stack person to finish it out.  

Put a place in Documentation for Blog posts?  More conversational - short and specific.  "This is what happens, in steps".  As a developer, if I want to jump in and bebug and fix, this is very helpful.

218 - PR last night  Spec to site so that when you run R-Spec, pushes Jekyll to basically run an R-Spec as if in rack.  Bess merged it.  Hadn't tied it into Travis at all, so there are a few things - set up a default rake, changes to format, format styler.  Clean-up in this PR, inside of Travis config an exclude directive, errant ruby files,  

Take a look at that - bumped ruby to .2.4.6 and 2.5.0 test against latest minor releases

Inside of spec helper - moved where HTML proofer was running - now built inside of spec helper.  HTML link checker, was commented out - still commented out.  

3 outstanindg PR's with 2 where we know why its held

Update on 61 - haven't had a chance to look at it.  

12 things ready to get picked up.  Lot of things stem from 186.  Our desire to have more ehnaced nesting of menu items. 

Is there anything else for tickets on the board.  

Maybe doesn't drive work, but does help us catch things.  Challenge is how busy everyone is - the documentation stuff is something people do on the side.  Don't want to lose touch just because we're busy.  Missing a PO to groom backlog, no stand-ups.  POs and standups move tickets through the board.  Without those two components - not moving as rapidly as we're used to.  

  1. Other discussion

Stuff in project boards - working

Update at LDCX - Documentation effort is underway - bring people in to do the documentation for their effort - still missing some key components to moving items to done.  Someone to organize the work and push.

There are other documentation efforts out there - some effort put toward them.  No written down coordination strategy - what do we tell people?  What do we do?  Open for business?  Put stuff in here or speak more forcefully?  A lot comes down to - how good is the site?  If site is working well and is where people want to put documentation - then people will put it there. 

Educational process to put documentation there.  Having someone who will put the content in order - what left-hand menu item is this under?  No real search.  There's a way to use Elastic Search with a Jekyll site.

AI:  we should add a ticket to add search.  Good site, has some value already.  It's not comfortable - from a knee jerk reaction, make it easier to look there.  If I know something - make it easier to add.  

AI:  Show people the site at LDCX - three of our pages that are really good.  Raise awareness.  Show up at LDCX - show 3 things and things we need help on.

Gathering community around this  - Hyrax has a lot of documentation around its WIKI.  Why duplicate efforts?  Can we get all content moved over - move content over to Samvera GitHub.  Anyone who has that bookmarked - driven over to the site.  States as goal:  move content over.  

One task:  Move all documenation into .io.  Someone could do that pretty quickly.  Lot of stuff in DuraSpace Wiki - dev doc should be around more developer-centric application.  Wikis of GitHub are separate.  

Can we ask PO's to move the documentation to this thing.  Reach out to PO's in general - trying to collect all documentation in one place.  What kind of doc exists and what can we move into the site?  Those should be our PoC's. 

Message to LDCX:  2 or three themes

  1. Look at all the great documentation we've already got  
    1. Highlighting fact we have groups bringing documentation - here's some examples of how it's done
  2. Continued effort to consolidation of documentation
    1. streamline communication for getting content into the site:  Reaching out to newly designated owners of certain repos to make sure that happens
  3. Next Steps:  What we need for resources from community
    1. An actual sprint dedicated to the documentation - 2 weeks of working on documentation
    2. Less to do with content and more to making content easier to manage
    3. Lay out technical things for developers to solve 

Set up a project board for structure and one project board for documentation efforts - Technical Board and Content Board

Challenge of getting FTE time.  Have 5 developers doing 4 hours per week.  (20 hrs.)  But has to be well organized.  Tickets doable within 4 hours.  Pushing and asking for someone willing to take an organizational role a requirement for a successful sprint.  

Lynette - firmed that up and placed her notes in Slack.

Seques into general org of site:

Haven't done work toward versioning  - only difference between work Drew was looking at and what Lynette had done.  Doesn't change theory of how this is documented.  

Site is organization wide - all of Samvers, not just Hyrax.  title of site is Hyrax Developer Knowledgebase.  More product centered and therefore version centered?  

When we've been implementing version metadata - it's been Hyrax.  Specifiying a version of Hyrax.  An excellent organizational approach.  At highest level - we jump into weeds right away.  Can have different menus in current framework.  Could have an Avalon left hand menu/ Hyrax Lefthand menu/ Shared Lefthand menu.  

First level - what flavor you want to look at, then product, then versioning below that

The flexibility makes code a lot messier.  Top level generic - Smavera COmmunity - general repository up there.  maybe a blog.  Drill down process.  Then product.  Then version.  Doesn't all have to be in left menu.  Theme taken from Jekyll how-to guides - so not married to current theme.  We could bust out of it if we wanted to.  

Check into next time:Didn't get to HTML proofer - still a lot of broken images according to proofer

Blog:  Talk about at LDCX - we don't have a way to find and coordinate blog posts from community - we could collect some of that stuff scattered around the community.  

  1. Facilitator & Notetaker for next meeting
    1. Facilitator:  Drew
    2. Notetaker:  Ryan

Action items