kubernetes
/
community
mirror of https://github.com/kubernetes/community.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
community/sig-docs/planning/2019-Q2-03-28.md

9.2 KiB
Raw Blame History

SIG Docs Q2 2019 Planning

Q1 Review, Q2 Planning

28 March 2019, 6-9pm Pacific

Authors: Zach Corliessen, Jennifer Rondeau, Jared Bhatti

Introduction (10 minutes)

  • Welcome and introductions

  • Overview

    • (Zach C) Proposals: not sure where best to include this section, we'll evaluate and iterate accordingly

Q1 Review (45 minutes)

Wins

  • 1.2 million page views per week! Up from 1 mil last quarter!
  • 1.14 Release (thanks Jim Angel and all the shadows!)
  • 2x number of localizations (French, Italian, German have been added!)

Goals

For each goal: carry forward to Q2? (Y/N)

  • Q1 (Jan-March)

    • Onboarding new devs / admins

      • Define the content plan (Steve Perry)

        • Deliverable: Github project w/ list of issues detailing new onboarding content.
        • Grade: .7, Very close to done
        • Carry forward? YES

      • What is K8s? (overview) (Brad, Andrew)

      • Setup --> Getting Started (Jennifer, Chris, Cody)

        • Deliverable: Formulate a list of milestones for Chris. Define new list of content.
        • **Grade: .1, discussion and plan in progress, blocked on hiring. **
        • Carry Forward: Yes

      • Redoing User Journeys (Andrew)

        • Deliverable: Create plan and hand off to another.
        • Grade: 1, Done, in card-based system now.
        • Carry forward? No, done :)

      • Admins: set up a cluster, how to secure clusters (Zach A)

        • Deliverable: Define a prioritized list of topics that need to be documented for users.
        • Grade: .4, Zach A created a working group and is making progress.
        • Carry forward? YES

    • 1.14 release (Jim Angel)

      • Release 1.14 docs, Defining/Documenting release docs process (Jim, Jared, Cody)

        • Grade: 1, Release in great shape
        • Carry forward? No, done :)

      • Deliverable: 1.15 handoff complete doc, create release playbook for 1.15 and ongoing releases, doc generation process is documented and works smoothly, & find a home for the content (sig-release vs contrib guide).

        • Grade .9 Doc in flight, Cody and Jim working on publishing in April.
        • Carry forward? No, done-ish?

    • Meta information architecture (scope and strategy) (Zach, Steve)

      • Deliverable: Make a decision on Pwittrock's Kubectl Docs, determine integration.

        • **Grade: .1 No decision made. **
        • **Carry forward: Yes, but deeper conversation needed on how SIG-Docs handles subdomain content. **

    • Accessibility (Rajakavitha Kodhandapani, Cody Clark)

      • Deliverable: Make plan with prioritized list of fundamental accessibility issues that need to be addressed.

        • Grade .5 Plan in progress, Draft Started (here)
        • Carry Forward: Two sections: One for accessibility for writers, one for accessibility for the site itself. What we have

Year-long 2019 Goals (30 minutes)

  • Onboarding new devs and admins

    • Setup --> Getting Started

      • Progress: 0

    • Explaining basic and intermediate concepts better

      • Do we approach content improvement by:

        • Analytics-driven?
        • SIG-driven?
        • (Zach C) Repo project with issues worked really well for Q1, let's carry that approach forward
        • (Brad) These aren't an automatic either/or binary; we can do both.
        • (Jennifer) What are our analytics telling us? Are they really a meaningful driver for doc improvement?
        • (Zach A) Examine page bounce rates/most time on page for metrics?
        • (Zach C) Bucket content, create issues, inform priorities by analytics, and get started. AGILE, not waterfall!
        • (Jim) Look at most-visited pages,

    • Expanding task documentation

      • Worth approaching separately from SIG-driven docs
      • New contributor AMA, blog post, reach out to existing channels, contributor day at Barcelona

  • Improving Docs Process:

    • Review PR review process (PR Wrangling)

      • In good shape, but provide time commitments/expectations clearly

  • Release Notes Process

    • Progress: Jennifer can mentor, but someone else needs to own/drive
    • Publicize this to find an interested contributor to own/drive
    • Mike Arpaia (sp?) can also mentor/review

  • Better CLI and Admin documentation

    • Progress: 0

      • Discuss after subdomain convo

  • Meta information architecture (scope and strategy) (Evaluating KubeAdm docs and FMC)

    • Models?

      • Andrew drove previously; we need a concrete plan for where they go and who drives it
      • Dominic's involvement is not unbounded; we need to respect his time
      • Steve Perry may be a useful resource/driver
      • Jennifer: Engage with Steve Perry as well
      • Jared: Create a blog post to detail the work/scope, provide examples, highlight the top posts

  • Security Documentation & Bulletins

    • Progress: Yes, Zach A is taking it on in Q2

  • Site UX

    • Progress:

      • Jared: Do we own this? We should decide. If we own it, then we need to find the expertise to do this?
      • Paris: Chat with SIG-UI!
      • Zach: We will likely need to hire someone
      • Jennifer: UX includes more than UI design, and should. Some of it is information architecture/content design, which sig-docs would need to own.

  • Accessibility

    • Progress: Yes, Rajie and Cody will drive in Q2

  • Version Skew / Docs [Jim A. - owning in Q3]

Break (10 minutes)

Proposals (45 minutes)

From Dani Comnea:

  • Differentiate the lifecycle/ administration (including how the certs are generated, how to rotate them, whether rotation is out of the box etc ) of a kubeadm cluster and the non-kubeadm cluster

    • (Jennifer) Remove the technical debt/resolve the information architecture for this specific task, may provide a model for others to follow.

  • Align the documentation tasks like "Operating etcd clusters" around the static pods.

    • Reviewing information architecture--if Dani wants to drive, great! Probably not a SIG-wide goal for Q2

  • Should "Install Minikube" task be moved under setup section?

    • Link from Setup, keep in tutorial

  • Group tools under Reference section under one sub-topic

    • Yes, we should absolutely re-organize IA in Q2.
    • (Jennifer) It's great, but let's plan it in Q2 and do it in Q3.
    • If Dani wants to drive, great!

  • Should docs move to a vertical approach like is been suggested https://groups.google.com/forum/#!topic/kubernetes-sig-cli/kJ2rbTffins? Maybe at least in the tutorial section?

    • (Jennifer) Narrative approach is historically complex; involve Steve Perry in discussion.
    • (Jared) Tutorial approach is narrative but semi-incoherent; narrative approach may make sense, but needs to be coherent. For other sections of the site, it may make sense to take a narrative approach, but--whose narrative? Makes clearer sense for tutorials.

  • How do we handle subdomains and their content?

    • Zach:

      • Danger: What is under the umbrella of SIG-Docs? Is our workflow a barrier for people who commit content?
      • Opportunity: This issue is due to the wild success of k8s. Listen and engage with content creators.

    • Jared:

      • Let a million flowers bloom, but let's set some standards as to what's in and what's out.
      • Do we provide some minimal content/requirements for subdomains? ("This is a subdomain for out-of-tree code. For in-tree code, visit kubernetes.io.")
      • Code of conduct adherence is mandatory.
      • We don't build anything; we provide pathways for integration.
      • (Zach A) We need to codify a statement of policy/intent/best practices for subdomain content.

From Zach C:

  • Provide structured opportunities for mentorship and contribution

    • New Contributor Ambassador
    • Issue Triage Captain
    • Whole path mentorship from New Contributor to Approver
    • Mentoring replacements for chairs

Q2 Goals (30 minutes)

  • Forward goals from Q1
  • Goals from yearly priorities
  • Goals from proposals

Q2 review/Q3 planning at KubeCon Shanghai with asynchronous involvement beginning 3-4 weeks before in well-bounded discussions at weekly meetings.