Date
Attendees
VM (Vicky) Brasseur (she/her), Juniper
Anda Nicolae , Lenovo
- Kieran Milne, Juniper
- Thulasidaran M, Juniper
- Rosemary
@Kieran Milne, Juniper
Agenda
- Review action items from 2019-03-20 27 Docs WG Meeting
- Discuss Edward Ting's resignation
- Select a new documentation lead
Minutes
- NO CALL - just notes below to review (some related to last week's AIs) and pick up next week
- Current state of the docs and possible updates/changes
- Current TF doc page is a bit of a 'running list' of items
- Could be updated/restructured to more clearly identify and point to the various available resources
- Current 'doc set'
- Current TF doc page is a bit of a 'running list' of items
- 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:
- Some community-created content at
- 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
- Project manager for the project
- VMB: Probably listed in the Community Governance doc, if it's anywhere:
- 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:
- An interesting mix of items, generally related to getting-started/install/deployment
- Perhaps reorg/consolidate (or remove, per backlogged AI below?)
- Some Juniper/Contrail-created content at
- Will stick with rst format for now
- contrail-docs
- The content here was a test of transferring Contrail 5.0.1 docs over to Github/rst content.
- It is essentially raw content (ie. real content but interlinking not established, etc.) .. intent was to stitch it together, but effort was abandoned
- See below for possible AI here
- API guide - currently on OC site, moving over to TF site
- Just FYI, Juniper will now also host a version of these pages on juniper.net/documentation
- Deploying/Quick Start Guide on opencontrail.org: 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?
- Have a nearly empty repo:
- 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
- This may need a total overhaul, but it's one of the most frequently hit pages on opencontrail.org so we should at least move it to tf/docs for now and add a "hey, out of date; stay tuned" warning to the tf/docs version and a redirect from opencontrail.org to the new tf/docs version.
- Moving forward - Some options to consider (not mutually exclusive)
- Center around community-created docs
- Parking this for today
- Leverage and transfer Juniper/Contrail docs to TF/Github
- It may be an option to reuse the content-transfer model described above
- The tooling to do this exists
- Would require 1) coordinating with Juniper's DigiEng team to transfer content, and 2) resources to (re-)thread the raw content together to make a full working doc set
- Link/point to Juniper/Contrail docs on juniper.net/documentation
- Instead of setting up around TF-created docs, simply point to existing Contrail doc set
- Perhaps create a page that mimic's juniper's Contrail doc landing page
- Clearly would not provide a true 'TF doc set', and there would be some details to figure out, but it would provide an instant full-coverage doc set
- The TF site already points liberally to github.com/Juniper; In at least one case, a github.com/tungstenfabric/docs page points to juniper/net.documentation, ie. this is not a fully new premise
- Center around community-created docs
Action items
- Review/merge minutes above with previous week, continue conversations
- 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
- - review notes above for discussion via email or on next call 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.