11:00 AM EST at https://cornell.zoom.us/j/703126880
Topic: Samvera Documentation WG
Facilitator: Andrew Myers
Notetaker: Ryan Steans
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.
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
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.