Meeting About Documentation 2016-09-01

Location

Attendees

• Jacek Becla
• Unknown User (xiuqin)
• Jim Bosch
• John Swinbank
• Frossie Economou
• Tim Jenness
• Jonathan Sick
• Zeljko Ivezic
• Mario Juric
• Mark Arndt
• Joel Plutchak

Proposal (to start discussion)

Scope:

1. Take inventory of all DM documentation including what lives where. Identify obsolete and out of date documentation
2. Identify missing documentation
3. Come up with structure (what goes where). Consolidate (reduce) the number of technologies we use for documentation, and clearly define boundaries what should be documented using what technology.
4. Define policies
5. Estimate work needed to remove obsolete documentation, fix out of date documentation and generate missing documentation
6. Prioritize the above work
7. Strategize how to do the work (hire new people? Tax each developer? Introduce documentation sprints?)
8. Do the work
9. Maintain / curate / keep current

Who?

• #1 - need a person who'd coordinate. Get help through crowd-sourcing by all DM?
• #2 - crowd-sourcing by all DM?
• #3-#7 - a small Documentation Tiger Team?
• #8 - new hire plus some people from DM?
• #9 - new hire?

When?

• #1, #2 - this CY?
• #3, #4, #5, #6 soon, but don't disrupt replan. Need rough estimate of resources needed ~Nov
• #7 - early next year?

Discussion Items

• Need to revisit LDM docs:
  • produce a map of top level docs (flow down is not always good)
  • revisit scope of what is covered in which doc (example, not clear if LDM-151 is just for design, or for scoping/resource loading as well)
  • all LDM docs must stay in docushare - project level policy
• Google docs
  • Massive growth of google docs
  • Curent situation is unacceptable, stories/epics are closed, they point to google docs that are scattered at random places. There is no process defined to govern this. Need clear policy
  • Google docs are fine for collaborative doc writing, but official/final versions should be transferred to official DM repositories
• Confluence
  
  • Need clear policy what goes on confluence
  • i has smaller role than it used to have (eg, lots of docs are being migrated to git)
  • Still good for things that have "low value once project is delivered" (like meeting notes)
• user docs
  • docs for each area is handled by the respective teams (eg pipelines by UW/Princeton, Qserv by SLAC, Firefly by IPAC etc)
  • SQuaRE will assist with standardization, writing top level entry, and providing tools.
  • Need to setup a team that will handle user docs. TCAMs from each team (or someone a TCAM designate) + Jonathan
• Would be useful to spell out different classes (types) of documents (design LDM docs, tech notes, user tutorials, etc)  
• Would be check with system engineering / Project Office, they already have structures for docs
• Doing the inventory
  • K-T did inventory of trac (post meeting question: all docs or only tickets?)
  • LDM-* docs: need to do the inventory, tbd who
  • TCAMs + Jonathan will handle
  • Confluence: Mark Arndt will help (25% FTE level), will be reaching out to DM experts more knowledgeable with contents if/as needed
• Next meeting - at DMLT F2F, reserve 2h 

Action items

• Jonathan Sick produce a new LDM doc that will describe classes of documents, processes governing them, how they are created, decision tree (who information goes to which class of documents) etc. Timescale: early S17 (~Dec 2016). To be reviewed / approved by PM: DM-7572 - Getting issue details... STATUS .
• Jonathan Sick and Tim Jenness document decision tree (which information goes to which type of documents). Timescale: ~next week ( DM-7572 - Getting issue details... STATUS )
  
• Jonathan Sick setup the tiger team that will handle user docs: DM-7580 - Getting issue details... STATUS .
• Jacek Becla decide when/how/who deals with making trac fully obsolete:  DM-9295 - Getting issue details... STATUS
  
• Jacek Becla coordinate revisiting LDM docs (now captured through  DM-7484 - Getting issue details... STATUS )
  
• Jacek Becla coordinate defining policies related to google docs and ensure they are clearly documented (now captured through  DM-7485 - Getting issue details... STATUS )
  
• Jacek Becla plug in Mark into DM
  
• Jacek Becla schedule 2h documentation discussion at DMLT F2F