2019-03-27 Docs WG Meeting notes

Date

27 Mar 2019

Attendees

• VM (Vicky) Brasseur (she/her), Juniper

• Anda Nicolae , Lenovo

• Kieran Milne, Juniper
• Thulasidaran M, Juniper
• Rosemary, Juniper

Agenda

• Review action items from 2019-03-20 Docs WG Meeting
• Discuss Edward Ting's resignation
• Select a new documentation lead

Minutes

• Action items from 3-20
  • None
• Edward's resignation
  • Just FYI that he has resigned
• New PTL?
  • VMB: Docs are in bad shape; we need a PTL with strong docs experience
  • Edward has nominated Anda
    • Anda doesn't have a lot of docs experience
  • VMB suggests maybe Kieran?
    • KM: What's the scope of the job
• Scope of the PTL job?
  • VMB: Probably listed in the Community Governance doc, if it's anywhere: https://github.com/tungstenfabric/docs/blob/master/Governance/TungstenFabricCommunityGovernance.rst
    • The PTL acts as the de facto spokesperson for the project.
    • That's the sum total of the PTL job description in the doc
  • VMB: Spitball a job description
    • Project manager for the project
      • Discovers & manages the tasks for the project
      • Participates in ARB/TSC discussions (whatever that looks like once the TSC figures it out)
      • Reports back to ARB/TSC (or gets someone else to do it for them)
      • Recruit new members to the project
    • Leader of the project
• Scope of work in general
  • What is current state of the docs?
  • Where do we want the docs to be?
  • How do we bridge the gap between these?
• Current state of the docs?
  • Have a nearly empty repo: https://github.com/tungstenfabric/docs
    • Will stick with rst format for now
  • Have some historical API docs: http://www.opencontrail.org/deploying-opencontrail/
    • Chaitanya will be moving these over to the /docs repo
  • And then we have…?
    • What sort of docs already exist in the /contrail repos?
• Tracking the work we need to do?
  • Use JIRA like the rest of TF
  • Need to come up with a process for using JIRA for docs 
    • And then document this
  • JIRA: https://jira.tungsten.io/secure/Dashboard.jspa
  • Maybe Juniper folks may have ideas about how to use this?
• JIRA tickets we'll need to create once the JIRA thing is sorted out
  • Getting Started doc
  • JIRA process
  • How to contribute (at least review/update this doc: https://tungstenfabric.github.io/website/
  • Case studies
    • Would also make good blog posts
  • Performance numbers
    • Would also make good blog posts
  • How do we want to organise docs?
    • At least a first draft
• Existing Contrail public docs
  • Juniper is working on a reorg of their own documentation: organised for purposes ("so you want to do…")
  • Maybe could repurpose that organisation of docs?
  • Couldn't re-use the docs themselves, since at Juniper proprietary

Action items

•  VM (Vicky) Brasseur (she/her) Ask TSC to update community gov doc to better describe the job description of PTL
• Kieran & team will have a look at the JIRA & give an MVP for JIRA process for docs
• VM (Vicky) Brasseur (she/her) Review public Contrail repos and locate docs that might exist in them
  

Backlogged Action Items

• ???: Get rid of community-docs repo (it's superfluous) ← do this after all of the repos are moved
• Current locations of all documentation: Defer until after the infra move is complete
• Current CI/CD status of documentation: Defer until after the infra move is complete
• Patch approval criteria for docs: Defer until the TSC confirms the process for code.