kubernetes
/
community
mirror of https://github.com/kubernetes/community.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
community/sig-docs/meeting-notes-archive/2017_Weekly_Meeting_Minutes.md

72 KiB
Raw Blame History

12/19/2017

NOTE: No meeting 12/26, Happy Holidays!

NOTE: Jared B. will run first meeting of 2018 (Zach on vacation)

New attendees?

Version 1.9 retrospective

  • Docs are live! Thanks to:
  • Topics for retrospective?
    • Feature docs:
      • Last-minute mess from an unclear PR
      • In the future, clean PRs only (no reverts/rebases)
    • Release notes:
      • Script adjustments, pull in descriptions from PRs
  • Future docs release meisters
  • 1.10: Jennifer Rondeau
  • 1.11: Nick Chase
  • Chris Short (@chris-short) wants to shadow a release

Docs summit 2018

  • Polling for interest in a SIG-Docs summit
  • Early 2018? May/June?

Supported documentation versions

Reviewer conventions in docs files (Steve & Andrew)

  • Follow-up: automation and names in front matter of file?
  • Andrew will follow up with tooling people to modify bots to specify category

Automation meeting

  • Do we still want to have an automation summit? I.e., a meeting dedicated solely/heavily to autogenerated docs
  • Set a date for early February

Building a community site (community.k8s.io) for developer contributions:

From Joe Beda:

https://github.com/kubernetes/community/pull/1401/files

As we start thinking about KEPs and community guides I think it makes sense to consider a new site that is community facing (vs. user facing).  This is something that came up in the last SIG-architecture meeting.


Concretely, I'd like to find a way to have a good cross-indexed and nicely looking site to expose the KEPs.  But there is a need to make our community facing documentation much more approachable also. The pile of markdown files in github isn't working well IMO.
  • Follow up on streamlining the contributor process
  • Contributor user journey (Andrew/Paris)
  • Action item: Steve will take on for study and report back in Q1

What to do with Kops docs?

  • Talk about provider-specific docs in January (date TBD, Chris Love invited to join)

12/12/2017

NOTE: No meeting 12/5, KubeCon or bust!

New attendees?

  • Chris Short (Michigan)

Doc sprints at Kubecon (Zach)

  • How’d they go?
  • Steve: one improvement: different way to claim an issue (hard to track in Slack, doing it in issue create overlapping edits)
  • Jennifer: confusing to have first-time contributor review sprint PRs, created need for multiple review rounds: shepherd first-time contributors into creator roles, not reviewer roles
  • Registration: remove cap? Expose cap?

Version 1.9 status

  • Steve: Here are the four PRs for the auto-generated ref docs.
  • Steve: What's the plan for the remaining PRs for release-1.9?
    • Thaw, merge, re-freeze on Thursday 12pm PST
  • Zach: Release cut delayed until Friday
    • Send email to sig-docs-maintainers about freeze
  • Jennifer: A heads up or two for retrospective/lessons learned/proposals for 1.10 release notes
    • For release notes: embed docs contributors in other SIGs early in the release process?
    • Talk with Sig-PMs/release meister EARLY in the release process

Future docs release meisters

  • 1.10: Jennifer Rondeau
  • 1.11: Nick Chase

Supported documentation versions

  • Current+4 (as of 1.9, that means 1.9-1.5 docs are published)
  • Add release playbook to repo (including release notes)
  • Specify in style guide that supported versions = current+4
  • Specify that we do not accept PRs against older versions

Reviewer conventions in docs files:

  • Follow-up from 11/28
  • Tech reviewers: set up a discussion about conventions (reviewers in front matter? OWNERS file?) and automation
    • Set up OWNERS file for automation (categories for tech review by SIG)
    • Add SIG names to individual file front matter (Andrew & Steve will research)

Note for 2018: Revisit automation after 1/1, aka “automation summit”

11/28/2017

New attendees?

Doc sprints at Kubecon (Zach)

  • Where are we at?
  • Send questionnaire to participants: poll for experience level/pre-load participant distribution [zach]
  • Jason K is local to Austin and can help ferry donuts

Proposal: issue bankruptcy (Zach)

  • Managing backlog of issues we can’t or won’t touch
  • Monthly triage to close issues that haven’t been updated in past 6 months
  • Provide specificity in closing comments
  • Provide notice initially
  • Ongoing monthly maintenance
  • Triage issues in kubernetes/kubernetes

Mentoring program (Paris)

Note for 2018: Revisit automation after 1/1, aka “automation summit”

Auto generation of ref pages (Steve)

  • The scripts for generating the federation docs were broken, but have been repaired. Thanks to Maru Newby. PR 158, PR 157. These scripts generate the docs that we publish here and here.
  • I'm still working on PR 6366.

11/21/2017

New attendees?

Versioning follow-up (Zach, Steve)

Doc sprints at Kubecon (Zach, Jennifer)

  • Where are we at?
  • Steve Perry will be a facilitator!
  • Create a project dedicated to the doc sprint, more chunkable/understandable in context of a single sprint
  • Schedule a short meeting with Andrew, Jennifer, Steve

Auto generated reference docs (Steve)

11/14/2017

New attendees?

Auto generated reference docs (Steve Perry)

  • Delayed one week: 11/21

Improving Kubeadm reference (Fabrizio)

Google Container Engine name change

Kubecon doc sprints (Zach)

  • Reaching out to registered participants this week (by Friday 11/17)

11/7/2017

  • New attendees? *
  • Steve (via Ahmet): Search for "kubernetes deployment". The top result is a paid advertisement that goes to the Platform 9 site. In general, is this type of thing something we should be concerned about?
    • (Zach) From Dan Kohn: \
  1. It’s not that problematic. \
  2. There’s nothing we can do about it.
  • Improving Kubeadm reference (Fabrizio)
  • Doc sprints at KubeCon
    • Update on user journeys for doc sprints: Jennifer Rondeau
      • There’s suitable work to support discrete aspects of user journeys
      • Repo labels: help wanted
    • Consider options for two rooms: one SIG structured (user journeys), one participant structured (individual/small team goals)
      • Encourage K8s experts to choose user journeys
      • User journeys: help wanted label
      • Glossary: [Issue #5993]
    • Reviewers needed: if you’re not attending, you can still participate!
      • Tuesday 1-5pm December 5th
    • Custom t-shirts for SIG-doc attendees ;-) (Radhika)
    • Social media outreach to spread the news about K8s Doc sprint (Radhika)
      • Boost visibility for SIG
    • Usability study (questionnaire to distribute among randomly selected K8s users)? (Radhika)
      • Meet UX people at Kubecon
      • Poll after user journeys are released
  • Tech reviews (Zach)
    • We need a fresher list of tech reviewers with a wider base of issue coverage
    • Work with Paris Pittman to get a list of reviewers per SIG
    • Use @mentions to ask for a reviewer from that SIG
    • SIG-contribex is working on mentorship process
    • Check kubernetes/kubernetes for OWNERS file
      • Talk with people who work on Kubernetes robots to find reviewers
      • @cjwagner

10/31/2017

  • New attendees? *
  • Agenda items
    • Doc sprints KubeCon (Jared)
      • Is there a pre-reg list? (Ask Jared) Yes!
      • Is there a way to contact sprint registrants? (Jared/Sarah Novotny)
        • Send notification for license agreement
    • i18n update (Zach)
      • Fixing original docs is a non-goal for translation
      • Mature style guide: explicit standards for internationalization (action item for Zach)
        • Include explanations for why guidelines are in place: readability for English speakers of all levels
        • Standards to mention: present tense; aim for reusability long-term; minimize text in diagrams
        • Expectations for L10n workflow: what do we set, what do they set?
        • Specify separation of labor
        • Provide a method for upstream contribution
        • Set expectations for how commits are made/bundled (commits need to not be made through website)
    • Kubernetes version requirements for tasks and tutorials in 1.8 docs (Steve)
      • Example
      • Versioning content: we need to figure it out!
      • Revisit on 10/31 for deeper discussion
      • Pertinent to GKE as well: when is it appropriate to update documentation? How to position new API/K8S versions to users on older versions? (Ryan)
      • Specify required Kubernetes version in "Before you begin" for tasks needing a higher version due to an apiVersion change.
      • Steve to provide example solution at next meeting.

10/24/2017

  • New attendees?
    • Peter Zhao
  • Agenda items
    • Doc sprints KubeCon (Jared)
    • Docs development branch (Jordan Liggitt)
    • Monthly 404 update (Zach)
    • Translation efforts: changing scope (Zach)
      • Fixing original docs is a non-goal for translation
    • Kubernetes version requirements for tasks and tutorials in 1.8 docs
      • Example
      • Versioning content: we need to figure it out!
      • Revisit on 10/31 for deeper discussion
  • Code sample styling prototype, Part 2 (Jessica Yao)

10/17/2017

  • New attendees? *
  • Agenda items
    • 1.9 release shadow
      • Need a shadow for the 1.10 release (must be a sig-docs maintainer)
        • Brad Topol, Abigail McCarthy, Jessica Yao (will follow up)
    • Recent updates:
      • Glossary
      • Chinese translation process
    • Doc sprints KubeCon
    • How to improve kubeadm reference doc (Fabrizio)
      • Goal to improve docs for 1.9 release
      • Currently maintaining pages manually
        • Want to improve reference docs like kubectl or kubefed through automation
      • Want to add docs for advanced topics
      • Fabrizio and Joe Heck will talk more about automation
    • Code sample styling prototype (Jessica Yao)
      • It looks awesome :-)

10/10/2017

  • New attendees?
    • Anthony Bushong at Google (welcome!)
  • Agenda items
    • Doc sprints (Jared)
      • Write the Docs Melbourne (Issue, TBD): Friday, November 24, 9am-12pm
      • Kubecon (Issue): Tuesday, December 5, Time: 1pm - 5pm
    • Onboarding for new contributors (Zach)
    • Migrate K8s blog from Blogger to GitHub (#5823) (Zach)
    • Renaming kubernetes/kubernetes.github.io to kubernetes/website (Andrew)
      • Yes: Andrew will work to perform cutover
    • How To - Generated Docs (/docs/admin/…) and managing those (Joe Heck)
      • Document how to update docs; not with manual updates to generated output in docs repo.
      • Steve Perry has taken on automation process in general
      • Heckj will create a Google doc, coordinate with other collaborators; where to store it in GitHub is an open question (GitHub wiki?)
    • Glossary demo? (Jessica, Andrew)
  • Bump to next week
    • Code sample prototype (Jessica Yao)

10/3/2017

  • New attendees?
    • Brad Topol, IBM
    • Ryan Jarvinen (ryanj), Red Hat
  • Agenda Items
    • 1.8 release went out the door last week!
      • Thanks, Steve Perry and Jaice Singer Dumars!
      • Retrospective is scheduled for this Friday, October 6
    • 1.8 Release note writeup (Jennifer)
      • Seeking feedback in the doc
      • Jennifer/Radhika: improving visibility for release notes?
        • Where are release notes published?
          • Dual-sourcing content?
          • Build/site automation pulling build from another source?
        • How can we maximize quality?
        • Poll Jaice Singer Dumars (and Brian Grant) for vision on what users actually want from release notes
        • Two different challenges:
          • How to create content
            • 1.8 processes seemed to work really well; this seems solved
          • How to serve it/what do users need
    • Code sample formatting
      • Why is it the way it is?
      • Are we willing to consider adding prompts?
        • CSS and formatting for “best of both worlds”
      • Please keep bikeshedding to a minimum :-)
      • Jessica Yao will build a prototype for 10/10
        • Steve Perry requests: command format, output format, and how command/output will be explained
      • Continue this discussion at 10/10 meeting
  • Docs Sprint @ Kubecon
    • Date: Tuesday, December 5
    • Time: 1:00pm - 5:00pm
    • 30 boardroom seating, split across two non-conjoining rooms (this does account for AV)
    • There is a cost for renting the room during the conference, which I’m trying to figure out with CNCF/Community folks.
    • Any ideas for themes?
      • Glossary
      • User Journeys
    • Assistants: 4 (2 for each room)
    • Tracking issue: https://github.com/kubernetes/kubernetes.github.io/issues/5741
    • Jared is running a half-day sprint in Melbourne on Nov 27, guinea pigs abound! :-)

9/26/2017

  • New Attendees?
    • Chris Negus (Red Hat)
    • Andrew Burden (Red Hat)
  • Agenda Items
    • Updates on 1.8
      • Release notes (Jennifer)
        • Radhika and I are working through new edits.
        • Focus is on content
        • Lot to say in the retrospective today
        • Getting the information from SIGs, chasing folks down. Started with SIGs now going after individuals.
        • Features vs. Issues vs. PRs. What should release notes refer to?
        • Is there a space between automating everything, and a human chasing every release note down?
        • Process and/or tools needed. Jennifer will write up a plan.
      • Feature docs (Steve)
    • New maintainers
    • Documentation of cloud providers config (Luke).
  • No presentation today from Radhika; will reschedule for the future.

9/19/2017

  • New Attendees?
    • heckj - Joe Heck
  • Agenda Items?
    • Updates on 1.8
      • Release notes (Radhika)
        • Cutoff date was September 9, but deadline extended until testing is more stable
        • More PRs coming in, working with Jaice DuMars
      • Feature docs (Steve)
        • Large influx submitted within past day
        • Reviewers welcome! 1.8 release branch/1.8 milestone to find PRs for review
      • 1.8 tracking board
    • Community & Repo Maintenance
      • 126 open PRs in queue
        • 21 in 1.8 milestone
        • 18 in Chinese translation milestone
        • Only 13 need tech review
        • Review help is welcome! (Stick to 1.8 branch for now: needs tech review)
        • Lots of tiny PRs; in the past, release time = more PRs
        • Difficult to parse relevant PR's due to low signal:noise ratio.
        • Come up with a scalability plan for PRs two weeks after release
      • Monthly 404 maintenance
        • 404s are leveling off post-netlify deploy
        • Props to Andrew Chen for clearing the log!
      • GitHub UI bug (Zach)
        • Contacted support about UI behavior for “allow edits from maintainers”, waiting for a response
        • In the meantime, how do we want to alert contributors to the workaround?
  • Presentation: open source projects (Radhika)
    • Rescheduled for 9/26

9/12/2017

  • New Attendees? *
  • Agenda Items?
    • Repo labels (Zach)
      • Down from 154 to 30 #5339
      • By request, new label for tutorial-related content: team/katacoda
      • If we need a label and there isn’t one, open an issue
    • Updates on 1.8
      • (from Jennifer) Where are we at with release notes?
        • Short with information: many changes remain undocumented
        • Jennifer will approach contributors from feature development; may ask for help from other docs contributors
        • Need affirmative information from feature developers, even if there’s no release notes needed
      • Herding cats: still in progress :-)
      • 1.8 tracking board
    • Kubernetes code contributor guide #892 (Andrew)
      • Update: Andrew’s working with Paris
        • Need two key people: Michael Hausenblas & Jorge
        • High level framework first
        • Initial MVP shouldn’t be too difficult; initial materials already exist, have been assembled by Michael
    • Chinese Translation Project (Andrew)
      • Request from translation team for a special monthly sync meeting:
        • Schedule a first meeting: 8am PDT / 11pm Beijing
      • How many times does it need to repeat?
        • Unknown; do one first, then figure it out.
    • Handling PRs with the “Needs Tech Review” label (Zach)
      • There’s a list of tech reviewers
        • @mention reviewers as needed
        • Help keep the list fresh!
        • Zach will open an issue describing updates to contributor docs: if someone wants to submit a PR, that would be awesome.
        • Let’s single source this info!
    • From Jennifer: How much latitude do we have to say yes/no to PRs based on language quality?
      • We have a lot of latitude when it comes to quality of information
      • TLDR: use your best judgment
      • It’s OK to work on language in the PR
      • We can ask contributors to allow edits from maintainers and make language changes for them

POSTPONED - Presentation: open source projects (Radhika)

9/5/2017

  • New Attendees?
    • Jason Kennedy - Cloudy-things for IBM :)
  • Agenda Items?
    • Kubernetes code contributor guide #892 (Andrew)
      • Suddenly got a lot of attention
      • Lots of folks want to help
      • Paris - new community manager - helping lead this effort
      • Helping: Zach, Jennifer
    • Updates on 1.8
      • (from Zach) Write access to kubernetes/features--necessary to what degree?
      • 1.8 tracking board
    • Zach’s back
      • Thanks, Radhika, for doing issue triage!- Woohoo!
      • Zach will resume running SIG-Docs meetings next week
      • Catching up: message Zach on Slack with things that need attention
      • Added back to OWNERS to be assigned PRs :)
    • Feature repo access
      • Is that what we want? Do we need it?
      • We should have something like what we have for the docs repo.
    • Kubecon Docs Sprint (Jared)
      • Thanks Radhika for advice on running a sprint
      • Still waiting to hear back from event coordinators at Kubecon
  • Talk about experience about open source projects (Radhika)
    • 15-20 minutes.
  • Chinese Translation:
    • Organizing to bundle PRs into many PRs. Trying to reduce the barrage of PRs. Whoohoo :)
    • Any plans to do this for other languages? Not at the moment, since other language efforts would have to bootstrap themselves.
    • We should consider putting together a landing page in the docs to discuss localization. Gauging interest in other languages.
  • Docs analytics:
    • Tracking updated date to content? Is it easy?
    • “what are quality docs” — there’s a great blog post series here (starting with most recent): http://docsbydesign.com/
    • Google Analytics:
      • Standard site analytics
      • Customer SAT surveys
    • Github Analytics:

      • of issues against docs

      • Outstanding PRs to review
    • What metrics do we care about?
      • User satisfaction and happiness?
    • Timeline:
      • Q3: Strategize and research
      • Q4: Plan and implement

8/29/2017

  • New Attendees
    • James Turnbull - Engineer for 25 years, docs for docker and puppet
    • Michael Hausenblas - Red Hat, OpenShift
    • Damian Igbe - Cloud Technology Experts (CTE)
    • Tim Pepper - Open Source Technology Center - VMware
  • New SIG-Docs Maintainers
    • Vacation - please let Chenopis@ know
  • Agenda items
    • There should be a kubernetes contributor guide #892
      • General framework for user journeys created by Chenopis and others.
      • Good material in the issue
      • Who owns “contributor materials”? Unknown :)
      • Cuts across the following SIGs:
        • API machinery
        • Architecture
        • Contributor experience
      • Michael Hausenblas (compiling list of material), Andrew Chen (liaison with SIGs, scoping)
  • Additional Agenda Items?
    • Style guidelines for release notes (issue #5234, Radhika)
      • Radhika - you’re the first TW working on release notes.
      • We should tie release notes into the feature release process.
      • Create a suggested process for the 1.8 process.
    • Coordinating docs and release notes (Jennifer and Radhika)
    • Docs Home vs. Setup? (Jared)
      • Will be replaced by user journey portals.
    • Kubecon docs sprint (Jared)
      • Radhika, Chenopis, Jennifer Rondeau, James Turnbull, Damian Igbe

8/22/2017

  • New Attendees
  • New SIG-Docs Maintainers
    • Cody Clark (Yay!!!)
  • Agenda items
    • Luke: working on User Journey user/personas -- would like input in doc
    • Luke: Kubernetes Iconography Standards proposal
    • Jessica: Inconsistency between permissions of sig-docs-maintainers and kubernetes.github.io-maintainers on Github for force-merging PRs that are not up-to-date but don’t have merge conflicts (see Slack). [Note from Steve] This page shows the difference between Write permissions and Admin permissions.
    • Jennifer: quality of PRs
    • Radhika: Release Notes - collaborator w/ write access - you can merge :)
    • Steve: People who have been added to sig-docs-maintainers no longer need to be listed as outside collaborators. Is everybody OK with removing these people from the outside collaborators list?
    • Steve: Is it OK to add Zach to sig-docs-maintainers now. Currently his name isn't in the list.
    • Kubecon in December 7-8 - in Austin
      • Doc hack-a-thon?
      • Doc talk? Site talk?
    • Write the Docs - Melbourne Nov 24th

8/15/2017

  • New Attendees
    • Stephen Augustus - Field Eng @ CoreOS
  • New SIG-Docs Maintainers
    • Zach Corleissen
    • Jennifer Rondeau
  • Agenda items
    • Steve: Giving people analytics access
    • Luke: Doc to review for common diagram assets?
      • (<-- just reported that he’s at the doctor’s office, we should bump this to next time)
    • Zach: There are 144 labels (too many), but removals are permanent. He will get consensus & identify contingencies before deleting unused labels.
    • Zach: Will be on vacation from Friday of next week through Tuesday Sept 5.
      • Radhika will be doing issue triage! Hoorays!
      • Jennifer and Abigail are willing to do PR triage and merging. Hoorays!
      • Andrew will hand off incoming issues to Jennifer & Abigail.
  • Additional Agenda Items
    • Steve: Process for taking an issue. In the issue, create a comment that says, "@steveperry-53, @chenopis, I will work on this issue." Steve or Andrew will make you an outside collaborator with Read permissions. Steve or Andrew will assign the issue to you. In Kubernetes Doc Projects, Steve or Andrew will move the issue to the In Progress column.
    • We're considering adding additional reviewers to the OWNERs file to split the incoming pull requests among more than two reviewers.

8/8/2017

  • New Attendees?
    • Radhika - Core OS - 4th OS project - Rel-notes coordinate for the 1.8 release
  • Agenda Items to add?
  • Luke: On-Premises! Whoo. Andrew worked with Luke. Doc to review for common diagram assets.
  • Steve: If you would like to be a user of the Kubernetes Google Analytics account, either let me know on the sig-docs slack channel, or send me an email (stevepe@google.com). I need to know the username of the account you will use to sign in to a browser. I will submit a batch of names to Nate Kartchner later today. Going forward, people who would like to become users of the Kubernetes Google Analytics account can contact Nate Kartchner directly (nkartchner@linuxfoundation.org)
  • Steve: The GA account does not show search queries. But the Google Search Console does. This requires that you go through a short verification process.
  • Andrew: User Journeys [rough mock] [WIP project plan]
    • Looks good - let’s test this with a few users after we flesh it out further
  • Andrew: Version drop down UI [preview] [Versioned Docs Issue]
    • Make a larger announcement to the community about versioning
    • SEO - already de-listed - but does it work for site-search?
    • Good time to do another SEO audit.
  • Zach: Labels
  • Zack: Vacation
    • Triage needed for 8/21-9/5. Any volunteers?
    • Radhika will give it a try! Whooo.

8/1/2017

New Attendees?

  • Luke Heidecke - WELCOME

Additional Agenda items?

  • Formatting Callouts in our Docs - Cody
  • Steve: Playground links in prerequisites, PR 4550
  • Steve: Kubernetes Doc Projects
    • References issues in the repo
    • One of the docs maintainers would have to do it
    • Currently a feasibility study - how useful are “Projects” for tracking our issues?
    • AI: Steve will report back next week on the usefulness of Projects.
  • Luke: On-premise, On-premises or on-prem? Dictionary? Common diagram resource library?
  • Ahmet: About importing tutorials from kubernetes/examples repository.
  • Zach: Automation in the repo? What’s happening? Webhooks for labels?
    • AI: Jared will take offline with Zach
  • Andrew: Moving the Heptio folks along in the maintainers onboarding process
  • Diagrams:

Agenda:

  • Google Analytics for docs site -- export reports? What do we want to see?
    • Most visited pages | time on page ?
    • What else?

7/25/2017

Additional Agenda items?

New Attendees?

  • Jaice Singer DuMars (Microsoft, 1.8 Release Lead)

Agenda:

  • Steve: Added work items to kubernetes-documentation-projects. I propose we delete this doc, and instead track these work items in GitHub issues. The editing work items could all go in one umbrella issue. Each of the larger projects and smaller projects could have its own issue. And we could create a GitHub project for this effort.
  • Steve: What do people think of this idea? In the Tasks TOC, have two big buckets:
    • Tasks for Application Developers
    • Tasks for Cluster Administrators
    • Have further discussions -- revisit at subsequent sig docs meetings
    • Andrew: how about refactoring the /docs/home landing page into user journey portal? -- i.e. thread users through docs

Project Updates:

  • Andrew: move to Netlify update
    • moving to production today or tomorrow
    • v1-6.docs.kubernetes.io (example of versioned docs subdomains)
      • nav dropdown for version will be added after everything is live

7/18/2017

Welcome to the first weekly meeting. Wooo

Additional Agenda items?

Project Updates:

  • Steve is working on a document that describes writing projects: kubernetes-documentation-projects. This is where contributors can go to pick and choose a project. This document is a work in progress, and is currently in rough format. Steve will add detail this week.
    • Great work. How do we include this in the existing issue list? What’s the difference between a “Project” and an “issue”?
    • Github projects?
  • Zach is triaging all issues that are outstanding in our issues queue and reviewing outstanding PRs
    • Some statistics (so far) about open issues
    • Interactive tutorial is consistently biggest issue-opener
  • Andrew
    • v1.7
    • Moving to Netlify

7/11/2017

  • Agenda items to add?
    • What is the process to add jrondeau and jessicayao from Heptio as sig-docs-maintainers?
      • Attend SIG docs
      • Submit PRs
      • Add you to the group!
    • Working on updating community contribution guidelines, will give more information at next week’s meeting. PR in progress: https://github.com/kubernetes/kubernetes.github.io/pull/4324
  • New Attendees? (no)
  • K8s 1.7 Release Update and Post-mortem
    • The Kubernetes v1.7 release went out EOD 6/29. The corresponding docs were deployed to kubernetes.io shortly afterwards. There were no significant docs issues during the release cycle. Hooray!
    • Special shout out to Jessica Yao from Heptio and Cody Clark for helping w/ doc reviews. Thank you!!!
    • Andrew Chen (@chenopis) created a playbook for whoever wants to be the next docs release meister (aka Docs Lead for the Kubernetes release).
  • Netlify
  • K8s has a new SIG. SIG-Architecture
    • Break us out of having sig-silos. Get a big-picture view.
    • Big ideas
    • Bi-weekly, monday @ 10am, jrondeau, zach, jaredb, jyao will attend
  • Meeting update:
    • Moving to weekly meetings @ 10:30
    • AI: Add SIG-Docs to the community calendar.
  • Site revamp:
    • Working through content, some of them are going to be done by 8/15
    • Taking a family of topics and editing them.
    • Zombie project :) Just won’t die.
    • jrondeau and jessicayao

Followups:

6/27/2017

  • Agenda items to add?
    • Ahmet – tutorials moved from kubernetes/examples, where the content should live, where the manifests should live.
      • k8s.io/docs/samples is now removed and merged into /tutorials
      • I moved tutorials [1][2][3] to the docs site. But the manifests, source code for apps and Dockerfiles remain at kubernetes/examples repo. Should it stay that way? Discussion: kubernetes/examples/pull/16
        • Check with Jeff Mendoza about dockerfile.
        • Local yaml files
      • Setting up redirects from old tutorials at kubernetes/examples repo.
  • New attendees?
    • Zach Corleissen - CNCF editor. Hoorays!
    • Bob Reselman - Developer, journalist, researching OS, devops.com :)
    • Cody Clark - Google
    • Dan Kohn - CNCF
  • 1.7 Update
    • Original release date, 6/28
    • Release delayed to possibly Fri 6/30
    • Waiting on tech approvals (tracking spreadsheet)
    • Big launches / important items:
      • Security for multi-tenant clusters
      • Stateful set support
      • Api aggregation
      • Network policy
      • Encrypted secrets (Alpha)
  • SIG-Docs Strategy Shift Proposal (Devin)
    • Sarah Novotny requested a presentation at the k8s community meeting
    • Proposal for working with docs, out of the k8s leadership summit
    • Other SIGs are dependent on us.
    • In the past: worked on meta documentation tasks: Templates, launch processes, SEO improvements, information architecture
    • Moving forward: How do we increase our contributions?
      • Current interface: PRs which we respond to.
      • Get in front of the PRs, either thought having liaisons to other SIG meetings, or by inviting SIG-Leads to the meeting.
    • Dan:
      • CNCF governing board, aware that docs are under-resourced
      • Can we reach consensus on a request for headcount in the next month?
    • SIG-docs maintainers have to have some level of expertise in what the other SIGs are doing.
    • Goal: Get better communication between other SIGs and us. Move it up a level from PRs.
    • Next Steps:
      • Write up the needs and goals for improving sig-docs communication
      • Present at the upcoming k8s community meeting
    • Feedback:
      • Embedding folks in SIG groups is a large burden. Perhaps pick a few large, important groups to integrate with. Smaller groups will need to bring their story/documentation request to us.
      • Provide use-case personas
  • Moving to a once a week meeting
    • Next week, no meeting. Week after, moving to weekly meetings
  • Moving k8s.io prod to Netlify in Q3
    • Real server-side redirects
    • Potential to do versioned docs (which we’ll have to figure out how to do/support)

6/13/2017

  • Agenda items to add?
  • New attendees?
    • Sahdev @ IBM
    • Jessica @ Heptio
  • New starts:
    • Zack Corleissen - Editor CNCF
    • Cody Clark
  • Netlify
    • Evaluating when to roll this out, looking at ~2 weeks after 1.7 launch
  • Generating docs:
  • How do we share work that needs to be done better with the community, and get feedback from the community
    • Solicit help and content from Write the Docs
    • Help identify work items from people in the community
    • Share a doc of work-items for Heptio
    • Q: How are developers working with the docs?
      • Friction logs from new developers
      • Jorge has some info to share with the group
    • Q: Maintenance - Sig-docs-maintainers - How do you join the group? *

5/30/2017

  • Agenda Items to add?
  • New attendees?
    • New Starts:
      • Cody Clark - Google Intern on K8s
      • Charles Butler - Canonical (lead on canonical distro of kubernetes)
    • Potential Hires
  • Write the Docs - Kubernetes Docs Sprint Writeup (Jared / Andrew)
  • API Server Tasks and Tutorials?
    • Got a request for documentation on how to use watch on the api server from Joe Beda. I noticed that there isn’t must documentation on the API server in general.
  • Netlify Approved! (Andrew) [proposal]
    • Reasons we’re using:
      • Addressing upstream breakages - github updates won’t break us.
      • Uptime SLA provided. SIG-Docs is for content, not front end development :)
      • Host multiple branches - useful for versioning and testing UX
      • HTTPS support natively
      • Server-Side redirects for moar better SEO
      • 400/month - enterprise tier - figuring out the contract now.
    • Any questions?
      • Does Netlify support i18n standards?
        • Don’t know, but would be useful to merge in the chinese language docs.
      • When are we going to migrate?
        • Post 1.7, beginning Q3.
    • Does this/how does this change the contribution workflow for contributors?
      • No, it shouldn’t affect the contributor workflow.
      • PR > Site gets rebuilt > Goes live
  • Is there a local developer experience where they can view the content using the same stylesheets/etc?
    • We actually want to give alternatives to the local workflow.
    • There’s a difference between staging locally vs. staging using your own fork. Staging your own fork leads your topic to be indexed :(
  • Don’t know about local staging with Netlify, we’ll ask.
  • SEO (Steve)
  • Upcoming dates for 1.7
    • PRs - please open PRs by June 14th
    • Release slated for th 28th
    • Engineering feature repo - code freeze is this week, reviewing at end of this week
  • Sig-on-prem:
    • Needs some guidance on documentation
    • Looking to add examples for on-prem implementations
    • This should be done in combination with the docs effort on revamping Setup Guides

5/16/2017

  • Agenda items to add
  • New Attendees?
  • Write the Docs - Kubernetes Docs Sprint
    • Doc sprint process: www.tinyurl.com/k8s-doc-sprint
    • ~22 docs PRs filed (more PRs listed)
    • Lesson’s learned?
      • CLA process is terrible :(
      • Use the github login on the CLA page.
      • People were confused by how to use the template tags. Improve the process for using templates. {% include templates/concept.md %} should be called out.
      • Call out how to view the netlify preview. Perhaps break this out into a sep
    • AI: jrondeau will tweet about our awesomeness.

>>>>> gd2md-html alert: inline image link here (to images/Copy-of0.jpg). Store image on your image server and adjust path/filename if necessary.
(Back to top)(Next alert)
>>>>>

alt_text

Tools I’d like to explore:

5/2/2017

  • Agenda items to add
    • New Attendees?
      • Vanessa Wilburn - IBM
    • Content migration done. Hoorays!
      • User guides removed from top level nav
      • Migration is not complete in that topics are not edited, and not in the new templates, and some of them might need to be moved from where they landed. Shuffling will continue.
  • Issue triaging (ahmetb) need to create a gh team, work with wg-contribex to enable this
    • Current issues - 347
    • Bankruptcy for some issues
    • Don’t really have enough people :(
    • Upsides:
      • Improves responsiveness to users
      • Prevents buildup of issues.
    • Downsides:
      • Major refactors will accumulate open issues
      • Random assignments make it difficult to track duplicates
  • Discuss proposal: Moving examples/ out of main kubernetes repo (ahmetb) These are listed on k8s.io/docs/samples. Currently there are divided opinions. My proposal is that maintain only the maintained 4 samples to the new repo. Please weigh in with your opinions. There’ll be a followup meeting in SIG-Apps.
    • The samples directory as it exists was a bit of a “stop-gap”. In practice, it’s a crap shoot.
    • Duplicate use case to tutorials?
    • Remove samples from top-nav?
  • Process for adding suggestions for Tasks, Tutorials, and volunteers to write them? (chenopis)
    • Some of it is handled by the issue queue, but it gets lost.
    • Make a comment in the table of contents planning doc?
    • Spreadsheet for new content?
    • Issue queue - improve tagging (Andrew Chen)
    • https://github.com/jasonbellamy/git-label
  • UX Updates to the site?
    • If you see issues, please tag them.
  • Job Opening: Seeking a part-time editor for the site.
  • Netlify migration?
    • An informal “one major project per quarter”
    • Need to understand potential issues.
    • Why we want this:
      • Have to serve out to two named branches
      • Makes it easier to do versioned branches
      • Https support
      • Easier redirects (with support for 301 redirects)
      • Possibly has less outages than github pages. Better visibility into builds and logs :)
  • Locking down contributions
  • Write the docs:
    • Setting aside a set of content on the site that can be edited.
    • AI: Jaredb - Send a blurb with the content jrondeau@heptio.com

4/18/2017

  • New attendees
    • Jennifer Rondeau - from Heptio
    • Marco Ceppi - from Canonical
    • Joe Beda (late) - Heptio
  • Items to add
    • Maybe for next meeting: Netlify migration plan?
    • Knowing more about netlify would be useful :)
    • How much retooling (redirects, https forwarding) would need to be rebuilt?
    • Other sites on CNCF want to use netlify for staging.
  • Status of current projects
    • Docs migration (stevepe)
      • Finished in one sense. Everything is moved to its new home.
      • Not finished, in that content needs to be edited and refactored.
      • Some of the topics still show up in the old TOC
      • Next Steps:
        • Use the tracking sheet to continue to track the editing.
        • Provide a link to the style guides and make a group-editing effort
        • Docs fixit-week?
          • Potentially work on this during the “docs hack day” at Write the Docs?
        • Integrate engineering feedback on docs structure
    • Reference refactor (go/k8sio-ref-refactor)
      • Solid restructuring!
      • “API Overview’ under “using the API” needs a rewrite.
      • Jennifer is willing to help out.
    • 1.7 (ddonnelly)
      • Release Tzars: Dawn, Maru
      • Docs: Andrew
      • 1.7 branch is open

4/4/2017

  • New Attendees?
    • Luke from Weaveworks
    • Antonio Rosales from Canonical
    • Ilya from Weaveworks
  • Agenda items to add
    • Discuss adding dropdown menu in k8s.io (re: PR #2389) w/ Luke and Ilya
      • Context: KubeAdm Installation Guide
      • One of the choices that users make -> Which Network they’re going to use (Weave, Calico, etc)
      • Getting sent off to another page is a bad user experience.
      • No default is selected
      • Discussion:
        • Structure the documentation to improve the workflow?
        • Worries about maintenance burden
        • List the options? Can we do this by rewriting content?
        • Ilya described the issues that made tabs not appropriate as they’re currently implemented :(
        • Luke is willing to work with a writer on SIG-Docs for a rewrite, and look into a way to do toggled content via tabs or drop-downs on the site that is reusable.
        • Can we use Jekyll plug-ins? No, we can’t without moving off github pages :(
        • Andrew, Ilya, and Luke will work together and try to come up with something.
    • URL Structure of the site - post-Migration
      • Migration Status
      • Rearranging site structure significantly.
      • Migrating content from “guides” to “setup” “tasks” “concepts” and “tutorials”
      • We also want to change the URL structure of the site.
        • /tasks
        • /concepts
        • /tutorials
      • “Getting-started-guides” gets thorny :(
        • Current plan is to leave /getting-started-guides where it’s at.
        • Will be called “setup” guides on the page.
        • Kubeadm falls under this section.
      • Suggestion: Create a README with where pages moved to.
      • Andrew will own the redirects
    • Kubernetes Reference docs refactoring plan w/ Ahmet and Andrew
  • 1.6 Launch Review, 1.7 Prep
    • We will likely get a lot of questions about the new directory structure.
    • “Interesting release” process. Highest percentage of untracked pull requests.
    • Supposed to be a stabilization release.
    • Lessons learned:
      • We need to get involved earlier.
      • Andrew Chen will be taking the duty for the 1.7 release.
      • Release Czar should be determined tomorrow.
      • We could keep the deprecation notices around? Stevepe: No, we should remove those sooner rather than later.
  • Setup/Onprem Document Fixup (Jorge Castro)
    • At Kubecon we discussed with some of the people who care about onprem documentation if they would be interested in helping flesh out the “Setup” section of the proposed doc to match the depth and quality of the rest of the proposed doc structures.
    • We figure this would be a great place for sig-onprem to contribute to the docs. (Proposal)
    • We got some verbal nodding from those in attendance and would like to help out with this.
    • Discussion:
      • Once we break out “Setup” guides, create subsections with cloud and on-prem - use this proposal for on-prem
      • One concern: “I feel like I can be busting out a whole bunch of things to make this page better, but I don’t want to get in the way of the migration”
      • Stevepe: I can make a directory where the on-prem content can land.

3/21/2017

3/7/2017

  1. Any agenda items to add?

    1. Migration Status (Steve)
      1. Migrating Guides to Tasks - Tutorials - Concepts
      2. Reviewing new TOC today.
      3. AI: Will present at next meeting.
      4. Should be able to move quickly - Once we get the TOC, we’ll move first and edit later.
      5. Rough Timeline:
        1. EOM: Have TOC migrated.
        2. EO June: Clean up Content
    2. Questions: 6. What will the new migration look like? Is there a demo?

  2. New People 3. Shar: Works at Heptio (https://www.heptio.com/)

  3. 1.6 Update/Launch (Devin) 4. Following the release tracking board for 1.6: https://docs.google.com/spreadsheets/d/1nspIeRVNjAQHRslHQD1-6gPv99OcYZLMezrBe3Pfhhg/edit#gid=0 5. 1.6 docs PR should be targeted at the 1.6 release branch (not master)

  4. Giving members of the community access to the docs: 6. Step 1: Become a member of the Kubernetes organization. From the draft governance documentation, a kubernetes organization member should be: 7. An active contributor for at least 3 months; 8. A member of the relevant SIG-groups (Sig-Docs in this case) 9. Trusted enough to run tests on their own PRs automatically (or for docs purposes, understand our templates, style guides, and processes) 10. Follow the code of conduct 11. Have two-factor authentication enabled

     Once you have accomplished these tasks, ask the Sig-Docs leads (Jared, Devin, or Steve) and cc Sarah Novotny to add you to the kubernetes organization.
    1. Step 2: Apply to become a SIG-Docs maintainer 12. Ask the maintainersSig-Docs leads to add you to the newly-minted "sig-docs-maintainers" group. 13. The Sig-Docs leads will review previous PRs of yours and verify you as a member of the group. 14. Your name will be announced at the following SIG-Docs group as a group maintainer. Hoorays!
    2. Abigail McCarthy is our first new SIG-Docs Maintainer. Hoorays!

  5. Good info for Kubernetes: 9. Youtube Channel: https://www.youtube.com/c/KubernetesCommunity 10. Livestreams for GCP NEXT: https://cloudnext.withgoogle.com/schedule

2/21/2017

  1. Any agenda items to add?
  2. New People!
    1. Ianeta: works at Intel - Welcome!
    2. Abraham - Welcome!
  3. 1.6 is coming up quick - Release Branch Created (Devin Donnelly) 3. Devin Donnelly is managing 1.6 release. 4. Master branch is always live. 5. Devin will keep master in sync with the 1.6 branch. 6. Issues fixes should be pushed to master, 1.6 release feature docs should be pushed to 1.6 branch. 7. Netlify staging works for master. Devin will be set up for 1.6 after this meeting :)
  4. Have some notes on the getting started guides (Chris Hoge) 8. Just looking for a place to start filing issues and sending patches. 9. https://github.com/kubernetes/kubernetes/blob/master/CONTRIBUTING.md 10. https://github.com/kubernetes/community/blob/master/contributors/devel/README.md 11. https://groups.google.com/forum/#!topic/kubernetes-dev/XcYA6gLXYYE
  5. Update on content migration from guides 12. Pods -> Moving to tasks, tutorials, and concepts 13. Tracking spreadsheet: https://docs.google.com/spreadsheets/d/1DGnDEUo2Y9lxJkKmQmGfno-4qpTE8WIDgOi3QDI-MJM/edit#gid=0 14. If it says “Need owner” feel free to claim it. If it’s blank, ask first :)
  6. Issues are stacking up: 15. https://github.com/kubernetes/kubernetes.github.io/issues 16. Getting tech review 1. Code Sample Review 2. Engineering Review
  7. Audiences for our content? 17. Audience assessment? 18. People who are going to build a Kubernetes Cluster (Cluster Setup and Admin) 19. People who already have a kubernetes cluster setup and want to do something with it 20. AI: Share audience assessment with Sig-Docs
  8. Onboarding new contributors: 21. Slack Channel 22. Editing docs: https://kubernetes.io/editdocs/

2/7/2017

  1. Sparse meeting today. Summit happening.
  2. Any agenda items to add? 23. New folks at the meeting: 3. Ahmet Balkan: Googler working on k8s 4. Richard Edwards: Samsung CNCT in Seattle 5. Chris Hoge: OpenStack Foundation
  3. 1.6 is coming up quick 24. We’ll be creating a release branch
  4. Site migration update - building out concepts and tasks. 25. Some history: 6. Original site was organized around a large series of guides 7. Migrating the existing long-form guides into “tasks” “tutorials” and “concepts” 8. Created a tracking spreadsheet for content under guides, and migrating over to guides. Steve Perry is migrating tasks and tutorials, Andrew Chen is working on concepts. 9. Spreadsheet tracking effort: https://docs.google.com/spreadsheets/d/1DGnDEUo2Y9lxJkKmQmGfno-4qpTE8WIDgOi3QDI-MJM/edit#gid=0 10. If you’d like to contribute to the effort: 1. AI: Steve will take on labeling “needs owner” in spreadsheet for ones that are up for grabs. 2. Folks on SIG-Docs can grab them and start working. Ping Sig-docs if you have questions. We’ll be around to help. 3. We’ll check in at the next meeting. 26. Proposal for dealing with setup guides 11. Everything under “Creating a Cluster” should be in its own section.: Partner docs, using turnkey solutions, setup guides for folks not contributing to core k8s code.
  5. Helping us close issues

1/24/2017

  1. Any agenda items to add?
    1. AI: Update topic in Slack Channel - Done.
  2. Fixit congrats! (Jared) 2. From our original 530 issues, we're down to 202 open issues. All remaining issues have been prioritized and tagged. 3. Special thanks to Abigail McCarthy for coming up with our documentation prioritization process.
    4. Thanks also to Andrew Chen, Devin Donnelly, Steve Perry, and Jeff Mendoza.
  3. Adrienne Schroeder - Docs Editor (Jared)
  4. Migration for guides to concepts, tasks, and tutorials. (Devin) 5. Guides is an all-inclusive TOC (junk drawer) of content 6. Ground rules for migrating content: 1. “Guides” will eventually be deprecated. Content in guides will be moved to tasks, tutorials, and concepts 2. Deprecated pages will be taken out of TOC 3. Have a notice at the top with links to new content. 4. Eventually, deprecate old content. 7. Present at the next meeting. 8. Open questions: 5. “Setup Guides” location? 6. How do we handle redirects consistently? 7. How big is this migration? How many links are involved?
  5. Where can the community help? 9. Helping us sanity check the migration. 10. Testing our structure.

1/10/2017

  1. Happy New Year!
  2. Site Outages and Issues (Devin)
  3. Jorge’s issues with netlify (Jorge)
    1. Ubuntu Issues
    2. PR: https://github.com/kubernetes/kubernetes.github.io/pull/1932
    3. Travis: 4-5 issues identified when travis checks kicked on.
    4. AIs: Evangelize Docs processes and templates in other SIG meetings.
    5. Netlify: Jekyll issue. Likely a template failure?
      1. Log access: Jessfraz, Jaredb, stevepe, ddonnelly, pwittrock
      2. AI: Devin will take a look at the Netlify log.
  4. Docs Issue Triaging 6. New Process 7. For existing issues: 3. Pick an issue that hasn’t been labeled. 4. Verify that the issue is still accurate and valid. 5. Label appropriately 6. If it’s in the top 100 pages, look at the following spreadsheet: https://docs.google.com/spreadsheets/d/1pXfrCs2YlYjoFK5Z0mUmgSx_stMryhI-OmtGU8GXGN4/edit#gid=2130667426&vpid=A1 7. If the issue was created before 10/1/2016, and it isn’t actionable, close it. Please be aggressive about this. 8. If you’re going to be tagging issues, please let me (Jared) know so I can give you the proper level of access to do so.