Dual Hosted Tutorial Content

[thecrudge]

Problem:
Currently, the katacoda tutorials are embedded in the kubernetes website. The majority of the issues that get opened toward those tutorials are support requests, rather than issues against the documentation. Currently, these tutorials are also hosted elsewhere in the org, and this has raised the question about how to handle dual hosted content.

Proposed Solution:
Lazy consensus is that we remove the katacoda tutorials and link to them somewhere in the in the docs. Possibly the top level page that explains the tutorial.

Page(s) to Update:
https://kubernetes.io/docs/tutorials/kubernetes-basics/create-cluster/cluster-intro/
-> https://kubernetes.io/docs/tutorials/kubernetes-basics/create-cluster/cluster-interactive/

https://kubernetes.io/docs/tutorials/kubernetes-basics/deploy-app/deploy-intro/
-> https://kubernetes.io/docs/tutorials/kubernetes-basics/deploy-app/deploy-interactive/

https://kubernetes.io/docs/tutorials/kubernetes-basics/explore/explore-intro/
-> https://kubernetes.io/docs/tutorials/kubernetes-basics/explore/explore-interactive/

https://kubernetes.io/docs/tutorials/kubernetes-basics/expose/expose-intro/
-> https://kubernetes.io/docs/tutorials/kubernetes-basics/expose/expose-interactive/

https://kubernetes.io/docs/tutorials/kubernetes-basics/scale/scale-intro/
-> https://kubernetes.io/docs/tutorials/kubernetes-basics/scale/scale-interactive/

https://kubernetes.io/docs/tutorials/kubernetes-basics/update/update-intro/
-> https://kubernetes.io/docs/tutorials/kubernetes-basics/update/update-interactive/

[thecrudge]

/assign @zacharysarah
/assign @bradtopol

[thecrudge]

/cc @steveperry-53

[bradtopol]

So I thought the issue is we have a link like the following:
https://kubernetes.io/docs/tutorials/kubernetes-basics/create-cluster/cluster-interactive/
which is exactly the same as this:
https://www.katacoda.com/courses/kubernetes/launch-single-node-cluster

and that we should just instead link to the katacoda version so folks understand that this is Katacoda content and if they have any problems with the katacoda link and associated tutorial they should send their issues to Katacoda instead of mistakenly sending the issue to us because they originally used one of our links (i.e. https://kubernetes.io/docs/tutorials/kubernetes-basics/create-cluster/cluster-interactive/) to start the tutorial.
Am I understanding the issue properly?

If so then the work item is to find all our links that are just our version of the katacoda links and then replace our links with the corresponding Katacoda link. Also above the link we should describe what tutorial is run by the link, that it is hosted by Katacoda, and any issues with running the tutorial should be directed to the Katacoda support team.

[bradtopol]

/assign @BenHall

[k8s-ci-robot]

@bradtopol: GitHub didn't allow me to assign the following users: BenHall.

Note that only kubernetes members, repo collaborators and people who have commented on this issue/PR can be assigned. Additionally, issues/PRs can only have 10 assignees at the same time.
For more information please see the contributor guide

In response to this:

/assign @BenHall

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[thecrudge]

@bradtopol

That is the exact issue. I was only suggesting we link to it the top level page, for those interactive links.

[BenHall]

Thanks for the feedback. The content in the documentation is only available via Kubernetes.io. It was previously (2017?) a separate website from both Kubernetes.io and Katacoda but the content merged into the main website before it went live to provide a seamless experience for users.

The two scenarios you mentioned are both discussing how to start Minikube, but the Kubernetes docs go into more details about updating, scaling, exposing applications which isn't covered.

I'd prefer that we create a solution which keeps the content within the platform as it provides a lot of value to the doc users, but also that we can reduce any overhead on the docs team. Internally, we have already been discussing how we can help upstream docs more and we can certainly invest more time to support the tickets, both in the terms of the content and the platform.

To provide a summary of tickets, there are currently 21 open issues related to the pages. 5 related to platform improvements (users hitting a capacity error, pod taking too long to start which @gsoria is currently working on and the upgrade to 1.13 last week should have helped), 4 related to the proxy not running, 6 related to content (deprecated warning) and 4 that need more info or should be closed.

Here are some of my suggestions:

1. We move the content into the main repository. This will allow content changes and improvements to be more in a consistent way. Previously this wasn't possible (based on when it was a separate site) but was recently added to support Thanos and the workflow they wanted. This makes it possible for all the content to be powered by the site repository.

2. The use of Kubectl Proxy seems to confuse people. When the proxy isn't running, they get an unhelpful error and raise the ticket. We've made a series of attempts to make this clearer, but we can certainly look again. With the kubectl run and --port= being deprecated, it could be a good time to change those couple of steps.

Alternatively, we can also look at the platform ensuring users don't try to run the cURL command before it's been started.

3. We commit to being more proactive on the issues. Maybe we can setup a extension to the bot which automatically assigns the issues to us if they have been created via one of the interactive pages?

4. It would be great to be able to close issues that have been fixed or related to another issue (such as above). Alternatively we can comment and indicate that it should be closed by one of team.

I look forward to hearing your thoughts.

[BenHall]

I just went over the initial tickets I could find to do some initial triage and responded. I believe a number of issues can be closed. We will continue to monitor and respond accordingly.

The main issue I wasn't aware of was #12968 and the impact it was having. This was related to the hello-minikube content. While the content mentions the solution, people just clicked the link, see the error and raise a ticket.

We are now showing a friendly error message which will hopefully stop users raising issues.

[steveperry-53]

These are the two places I know of where you can view and interact with this content: Kubernetes Bootcamp <https://kubernetesbootcamp.github.io/kubernetes-bootcamp/index.html> Kubernetes Basics <https://kubernetes.io/docs/tutorials/kubernetes-basics/> Apparently, the two sites have fallen out of sync. In my mind, this is the fundamental question: Is the Kubernetes Bootcamp <https://kubernetesbootcamp.github.io/kubernetes-bootcamp/index.html> site going to be maintained? If yes, then we should take down the Kubernetes Basics pages, and instead provide a link to Kubernetes Bootcamp. If no, then we should take down the Kubernetes Bootcamp site.

…

On Tue, Aug 13, 2019 at 2:35 AM Ben Hall ***@***.***> wrote: I just went over the initial tickets I could find to do some initial triage and responded. I believe a number of issues can be closed. We will continue to monitor and respond accordingly. The main issue I wasn't aware of was #12968 <#12968> and the impact it was having. This was related to the hello-minikube content. While the content mentions the solution, people just clicked the link, see the error and raise a ticket. We are now showing a friendly error message which will hopefully stop users raising issues. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#15787?email_source=notifications&email_token=ADJHMDWZT6APFYWZ7Z3WIATQEJ545A5CNFSM4IKZIBG2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD4FDTFI#issuecomment-520763797>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ADJHMDWIRUZJ2EVLR2D2VTLQEJ545ANCNFSM4IKZIBGQ> .

[zacharysarah]

@BenHall 👋 Thanks for sharing your observations.

I echo @steveperry-53, @bradtopol, and @thecrudge in their concern. Dual-sourced content isn't acceptable. Tutorials need to reside at one URL or the other.

The Kubernetes Basics tutorial ranks consistently in or near the website's ten most-visited pages. The future of tutorial content is an important issue.

Support gap

SIG Docs experiences a support gap with Katacoda. SIG Docs maintains a website that hosts dual-sourced content, records tutorial issues and triages them, but receives only intermittent support from Katacoda, without any content visibility or service level agreement (SLA) about when or how issues are monitored or fixed.

I appreciate your good grace in responding to and addressing concerns for the past two years, @BenHall, but the way things have been can't be the way they continue. We need a sustainable model that includes clear expectations of support, timeliness, and communication.

We move the content into the main repository. This will allow content changes and improvements to be more in a consistent way.

Frankly, I'm skeptical.

Who does Katacoda propose will maintain this content? Will it just be you, @BenHall? (Would you ever be able to take a vacation again? 😳) Is Katacoda willing to field a dedicated headcount for tutorial content, with the understanding that ongoing hosting is tied to a minimum level of staffing? Is Katacoda willing to explicitly state this?

Unless Katacoda guarantees headcount for support, transferring content into k/website only shifts maintenance with unclear expectations onto an overburdened community. Without dedicated support, my answer is no.

The use of Kubectl Proxy seems to confuse people. When the proxy isn't running, they get an unhelpful error and raise the ticket.
...
Alternatively, we can also look at the platform ensuring users don't try to run the cURL command before it's been started.

These examples and this comment illustrate the support gap named above. ☝️

Maybe we can setup a extension to the bot which automatically assigns the issues to us if they have been created via one of the interactive pages?

A CI integration is pretty but useless without an SLA that explicitly states who fixes tutorial issues, when they'll be fixed, and how communication happens. Automation per se solves none of these concerns.

It would be great to be able to close issues that have been fixed or related to another issue (such as above).

If Katacoda provides dedicated staffing with an SLA, it makes sense to extend approver privileges for k/website to that staff.

TLDR

Tutorial content is valuable, but it requires dedicated, explicitly-stated support to continue at kubernetes.io.

Resolve dual-sourced Bootcamp content by removing it at one site or the other.

CC: @jimangel @Bradamant3 @kbarnard10 @jaredbhatti

[zacharysarah]

Lazy consensus

I want to make sure this issue gets adequate discussion, but I also want to make sure there's clear expectations about what happens by default. I also hope it's never something we have to act on.

For Katacoda tutorials to continue residing at kubernetes.io/docs/tutorials, the following must be true by 15 September 2019:

• Katacoda provides a clear SLA to SIG Docs chairs with minimum levels of staffing, response times, and fix times.
• SIG Docs chairs agree on SLA provisions.
• Content is single-sourced. The Kubernetes Bootcamp site is taken down and 301-redirects to the relevant tutorials on kubernetes.io.

Otherwise, SIG Docs will remove tutorial content at its discretion. SIG Docs may provide 301 redirects to Katacoda URLs at the best of its ability, but will not assume responsibility for ensuring correct redirects.

EDIT: I missed @thecrudge's original proposal for lazy consensus. Bad chair! 🗞
The original:

Lazy consensus is that we remove the katacoda tutorials and link to them somewhere in the in the docs. Possibly the top level page that explains the tutorial.

➕ with specifics as enumerated ☝️

[BenHall]

To provide an update on the dual content issue. I've investigate the Kubernetes Bootcamp and refreshed my memory. Last year I did make changes to the website bootcamp to automatically redirect to the Kubernetes Docs in an attempt to close it so we didn't have this issue. However, it looks like there are two repos (unsure why) and the website wasn't pointing that the intended repository.

I have now sent a PR to the original owners (kubernetesbootcamp/kubernetes-bootcamp#6) and also a Twitter message. Once merged, the content will hopefully redirect accordingly.

I don't believe anyone on this thread has permissions to the repo so I have also added a redirect so the interactive content is never displayed and users are alerted where to go instead as shown below.

The interactive section of the content is no longer dual hosted and dedicated to Kubernetes.io.

[jocatalin]

Hi, I'm the content creator of the original bootcamp tutorial. AFAIR @pwittrock created the kubernetesbootcamp.github.io organisation as an intermediary step, before having the code merged into the official k8s website. @pwittrock can you please merge @BenHall 's PR and eventually archive/disable the GitHub branch publishing for kubernetesbootcamp.github.io I don't have rights anymore on that organization.

[sftim]

/priority backlog

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[sftim]

/remove-lifecycle rotten

[sftim]

/sig docs

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

[k8s-ci-robot]

@fejta-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.