diff --git a/sig-docs/planning/2019-Q2-03-28.md b/sig-docs/planning/2019-Q2-03-28.md new file mode 100644 index 000000000..6f468bcc6 --- /dev/null +++ b/sig-docs/planning/2019-Q2-03-28.md @@ -0,0 +1,232 @@ +# 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.