# 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)

            -   Deliverable: Plan out the concepts and content for a new user understanding k8s, meaningful progress on content.
            -   **Grade: .5, PR in flight. https://github.com/kubernetes/website/pull/12884**
            -   **Carry forward? YES**

        -   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***](https://hackmd.io/jB6Q7nSoTgiGcV4Oc_4rjg)**)**
            -   **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\]

    -   [*https://github.com/kubernetes/website/issues/14307*](https://github.com/kubernetes/website/issues/14307)
    -   [*https://github.com/kubernetes/sig-release/issues/626*](https://github.com/kubernetes/sig-release/issues/626)
    -   Example: [*https://www.kernel.org/*](https://www.kernel.org/)

# 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*](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.
