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