Versions Compared

Old Version 1

changes.mady.by.user Kieran Milne

Saved on

compared with

New Version Current

changes.mady.by.user Szymon Golebiewski

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Date

Attendees

Agenda

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'
  • 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
      /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: 

        • 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 
      tungstenfabricdocs
      • Will stick with rst format for now
      Have some historical API docs
      • 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?
    • Tracking the work we need to do?
    • 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

    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.