2022-01-24 Meeting: First draft of external documentation

ACTION ITEMS:

From Last Meeting

This Week

Agenda

• First draft of external recommendations
• Strategizing release

Meeting Materials

Recording

Recording:  Review Pre-First Draft of External Facing Documentation (2022-01-24)

Notes

Feedback on first draft

• Is there a definition of Activity Streams including the context of their usage?  Probably should be clearly in the Overview, in Architecture,  and defined under terminology.  Where to include a link to official activity stream documentation?  Recommended to consider putting at the top of section 3 describing Organizational Structures.  Intro paragraph between 3. Organizational Structures and 3.1 Entry Point.  
• Move Objectives and Scope ahead of Use Cases
• Double check links from descriptive paragraphs to official Activity Stream docs.  They don't seem to be in the text.  Minimally at the start of sections where they are used.  For example, link to Ordered Collection from the start of 3.1 Entry Point, and to Ordered Collection Page from the start of 3.2 Change Set.
  • Will the doc be read sequentially or jumping around randomly?  If sequentially, then top of section makes sense.  If randomly, maybe consolidate in terminology as opposed to including at every mention of the term.  So maybe a combo of these two approaches.
  • Add as Reference at top of each major section.  E.g. Reference: Ordered Collections at top of Entry Point.
• Concepts vs. Implementation specific terms (i.e. Entry Point vs. Ordered Collection)
  • How will people talk about it?  The way we express it may be how people will talk about it.
  • Entry point may drop into a longer running stream.
  • Want this to be easy to understand for those who already know activity streams.
• Entity patch, is that a generic term, or are we really talking about RDF Patch?
  • When introducing a section, if we want to recommend a particular technology, it would be good to be clear about that at the start of the impacted section.
• Doc should support...
  • close sequential reading - try to avoid including links every time a concept is mentioned
  • scanning - include good headings
  • keyword search - include keywords in each section where they apply to enable finding that section
• Move section 6. Consuming Entity Change Sets to section 7.  And make section 6. Producing Entity Change Sets
• Diagram
  • Is this an ER diagram?  If yes...
    • Each rectangle is seen as a set, so wondering why are there 3 boxes for Change Set?  In this diagram, the 3 Change Set boxes are showing how first, next/prev, and last work?
    • Why 3 rectangles for each Entity Change Notification?  Probably switch to one box.
    • Maybe add 1..m cardinality indications for each box

Strategizing release

• list of implementations similar to W3C
  • How close is LOC and Getty?  Can they serve as implementations?
• producers are often consumers - adopting this will facilitate their own usage
• allows for common tool sets that consume change documents
• reach out for feedback from major authorities, prioritizing those with larger change rates as they will benefit more from this
  • some are mid-decision about how they will approach providing data to the public, so this could be good timing to influence their approach
• producers concerns
  • want to know that consumers will consume
  • reach out to individually
  • developer time is generally already committed, how to get it on their workplan?
• consumer concerns
  • want to know that producers will use it
  • reach out through conferences, user groups
  • if high adoption, only need one consuming implementation to consume all producer streams
• create reference implementation for LOC and Getty to demonstrate value
• feedback 
  • for initial documentation (e.g. 6 week period for review and feedback before 1.0 version)
  • for reference implementations allowing documentation to be modified over time (e.g. need additional change types, changes to processes for producing and consuming)

Future Topics

• Notification to a single institution when a requested entity that was missing becomes available.  This will likely be outside the main change management stream.
• Value of diagraming to express changes as a means of conveying information around where data is being produced, where it goes, etc.
• Partial splits and partial merges.

Attendees:

Dave Eichmann
Christine Eslao
Nancy Fallgren
Steven Folsom
Kevin Ford
John Graybeal
Jim Hahn
Kirk Hess
Jesse Lambertson
Anna Lionetti
Alessandra Moi
Tiziana Possemato
Erik Radio
Lynn Ransom
Lynette Rayle
Greg Reeve
Amanda Sprochi
Vitus Tang
Emma Thomson

Absent: