search

kubernetes / website

Kubernetes website and documentation repo:
https://kubernetes.io
Creative Commons Attribution 4.0 International
4.44k stars 14.32k forks source link

Copy example button consistency in the documentation #45910

Closed spurin closed 2 days ago

spurin commented 5 months ago

This is a Feature Request

What would you like to be added

Examples in the documentation should always have the convenient copy button.

Why is this needed

Examples which are inline in the documentation such as EmptyDir, do not have a copy button option - https://kubernetes.io/docs/concepts/storage/volumes/#emptydir-configuration-example

Whereas examples that are provided as standalone files, do, we can see the stacked icon in the top right corner which provides a modal popup confirmation when clicked - https://kubernetes.io/docs/concepts/services-networking/network-policies/#networkpolicy-resource

From an exam viewpoint, especially in the likes of the CKA/CKAD/CKS where the exam is hands on, the copy button is a significant benefit. Whilst working towards the Kubestronaut certification, I frequently found myself bringing up the website developer tools when using the ctrl-shift-c keyboard combination in the linux desktop environment & firefox.

Although this combination works fine in the terminal, it does not work as expected in the browser and students then need to manually highlight, right click and choose copy, to make use of examples, or use ctrl-c (which is unique in this env for firefox, given that the shortcut for copy is technically ctrl-shift-c on linux).

Comments

Whilst I highlight this from an examination viewpoint, I also believe that consistency throughout the documentation would be beneficial.

k8s-ci-robot commented 5 months ago

This issue is currently awaiting triage.

SIG Docs takes a lead on issue triage for this website, but any Kubernetes member can accept issues by applying the triage/accepted label.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.
spurin commented 5 months ago

If anyone wishes to experience this in a similar environment to the exams in the review of this issue, you can use this to spin up a quick env with a linux desktop env in browser, via google cloud for free - https://github.com/spurin/cncf-psi-k8s-linux-simulator - Press the launch button in the repo and follow the tutorial on the right hand side.

Example showing text highlighted and ctrl-shift-c pressed

image
dipesh-rawat commented 5 months ago

The absence of a "copy" button on certain code snippets has a reason. This decision is based on the understanding that not all snippets are meant for users to directly execute; some are simply provided as illustrative examples in the documentation. However, for snippets intended for users to try out, especially those found in task or tutorial pages, incorporating the code_sample shortcode (refer to the documentation) is highly recommended to enhance the user experience.

spurin commented 5 months ago

@dipesh-rawat - Thanks for your feedback regarding the absence of the copy button on certain code snippets. I appreciate the rationale you've provided, it highlights the intention for the difference between illustrative examples and executable code snippets.

However, I believe there is room to enhance the user experience further by reassessing whether or not snippets should feature convenient copy functionality.

Consider the network policy example on Kubernetes' network policies page. While primarily a reference and less likely to be used directly, noted by the usage of specific IP blocks and the phrase "might look like this", this snippet includes a copy button.

The example for a PersistentVolumeClaim found on the Persistent Volumes page is an example that many users frequently copy and adjust only slightly for their purposes, it's a favourite amongst most Kubernetes Storage tutorials/courses and exam preps. The absence of a copy button here limits efficiency and accessibility.

In the tutorial pages, there are examples, such as the command kind create cluster --name psa-wo-cluster-pss where a copy button again could streamline user interaction. Supporting direct usage without the need to manually select and copy text.

A uniform approach where each code snippet, whether it is an illustrative example or directly executable code includes a discreet copy button may not only improve user efficiency but also provide the freedom to choose how to interact with the documentation.

Lastly, incorporating a copy button enhances accessibility for individuals with motor, visual, and cognitive impairments, as well as those using assistive technologies, by simplifying the action to a single click.

shannonxtreme commented 5 months ago

@spurin I think the only way that we could do this is if we changed our code highlighter from Pygments/Chroma to Prism: https://www.docsy.dev/docs/adding-content/lookandfeel/#code-highlighting-with-prism

Probably something that would need our Tech Lead to consider, maybe worth bringing up in the next SIG meeting?

spurin commented 5 months ago

Thanks @shannonxtreme

Sounds good, I'll aim to join one of the meetings to go through this 👍

Gauravpadam commented 5 months ago

@spurin You could bring this up on a SIG Docs meeting We'll wait on triaging this one till then

spurin commented 5 months ago

Sounds good @Gauravpadam - will also be good to connect some of the the names to faces/voices in this community 😁 hopefully see you there

sftim commented 5 months ago

Looking specifically at https://kubernetes.io/docs/concepts/storage/volumes/#emptydir-configuration-example, we should convert this into a downloadable manifest that will gain a copy button as a side effect. If that's what you'd like the docs to look like @spurin, you are welcome to send in a PR that proposes that change.

You can also file an issue for each example you find, and if you provide enough context, each of those is likely to qualify as a good first issue.

We have quite a few places where a syntax-highlighted YAML manifest should really be using the code_sample shortcode (basically: anywhere it's a valid manifest, and someone applying that manifest wouldn't be putting their cluster at risk). It's already our policy to do that, we just haven't finished documenting Kubernetes yet.

We intentionally don't provide a copy button for partial manifests or for anything that might be dangerous to apply (and we plan to keep to that policy). If we wanted to change the policy here, we'd want a SIG-level discussion about why that's now a good idea.

I'm not sure about this use case. The OS I use, Ubuntu, already makes it pretty easy to copy snippets (I can do this in each browser I routinely run).

PS It's plausible that an exam environment change will also make the need for a special copy and paste mechanism unnecessary. Adding special support for copying text snippets that people find on the website feels, to me, like the wrong fix.

sftim commented 5 months ago

/area web-development /priority awaiting-more-evidence

sftim commented 5 months ago

Writing as me, not as a technical lead for Kubernetes docs: I am wary to promote putting a copy button on shell snippets. I think there are two benefits of not doing that:

  1. You learn more by typing the commands and thinking about them than you do from copying and pasting without the thinking part.
  2. Tacitly encouraging people to uncritically run commands they find on a web page, especially against an infrastructure system such as Kubernetes, has a different risk: one day, the thing they copy and paste might be malware. See https://twitter.com/1mattmc/status/1168597134263889922
spurin commented 5 months ago

Thanks @sftim

Appreciate your feedback and insights as always. I provided the exam insights as an example use case more so than specifically catering for that environment.

For context, I've taken up my CNCF exam experiences up separately with the certification team and as a support request with the Linux Foundation.

At present, ctrl-shift-c doesn't function in the Kubernetes linux exam env as one would best hope. In Firefox, this combination is mapped to the browser dev tools shortcut. Ctrl-c however does work here so it's one combo for the terminal and another for the browser. I've suggested a fix for this which allows both ctrl-shift-c and ctrl-c to work interchangeably. Again, informational only and not specific to this feature request.

My experience in this environment initially made me wish for the convenient copy button and after thinking of this more, my viewpoint on this topic changed towards this being a generic change across the board for ease of use and accessibility. I'll often naturally use the copy button if it's there, otherwise I'll manually copy.

Constructively, I think it would be beneficial to have copy available as a default standard and a markup that we apply to remove this button for risky changes (for example, Network Policies deny all rules). I haven't however reviewed or analysed how many snippets/samples we have that would be deemed risky and if this would be viable from a Hugo viewpoint.

After raising this feature request I reached out to Devin Nance who was a participant in the diversity and inclusion panel I moderated at KubeCon Paris. He is blind and in his case, has full blindness. I asked the question as best as possible without a bias on an answer on how useful the copy button is from an accessibility viewpoint given that he would navigate the documentation differently to you and I, his response -

"I like the copy button because sometimes trying to highlight and copy the text doesn’t always work very well so it’s better if there’s an actual button".

I had permission from Devin to share this feedback in this discussion.

For transparency, this isn't an attempt to try and influence a change/direction from an inclusion viewpoint. It's to highlight alternative requirements that some of our users will benefit from. After hosting this panel and getting to know these people better, my views/perspectives on a lot of areas have been opened.

I very much respect and appreciate the historic efforts that have been made in the documentation (I'm a huge fan).

It would however be appreciated if we explore this consideration a little bit further with some alternative perspectives, discussions and viewpoints, even if we finalise that we remain as we are 🙏

spurin commented 5 months ago

Regarding the two points highlighted @sftim, thanks again and agree that students learn more effectively by doing.

Very valid point on the command security aspect and agree, it's going to be hard vetting all of these and maintaining future code safety, especially where external yaml files are referenced.

In light of this I retract my viewpoint of direct command line examples having a copy option.

Yaml examples, given the typical size, complexity and indentation , these may benefit from having a copy option and possibly the direction is as you've highlighted, moving particular samples (subject to risk) so that they become file based (and therefore inherit the copy function).

If this is preferred, maybe I can repurpose this feature request or create a new feature request outlining this. We could identify samples and target them as good first issues as you suggested.

sftim commented 5 months ago

How about filing a new umbrella cleanup issue about finding example manifests that could be downloadable, and turning those into downloadable examples using code_sample?

If there are other snippets where you think there should be a copy button, please use this issue to provide an example of those and make a case for adding a copy button there. We could consider staffing that (I think as a low priority).

For exam accessibility, let's track that as a separate enhancement. There's more than one way to solve it and we should hear from different stakeholders.

k8s-triage-robot commented 2 months ago

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

k8s-triage-robot commented 1 month ago

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

k8s-triage-robot commented 2 days ago

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

You can:

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

k8s-ci-robot commented 2 days ago

@k8s-triage-robot: Closing this issue, marking it as "Not Planned".

In response to [this](https://github.com/kubernetes/website/issues/45910#issuecomment-2360500879): >The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs. > >This bot triages issues according to the following rules: >- After 90d of inactivity, `lifecycle/stale` is applied >- After 30d of inactivity since `lifecycle/stale` was applied, `lifecycle/rotten` is applied >- After 30d of inactivity since `lifecycle/rotten` was applied, the issue is closed > >You can: >- Reopen this issue with `/reopen` >- Mark this issue as fresh with `/remove-lifecycle rotten` >- Offer to help out with [Issue Triage][1] > >Please send feedback to sig-contributor-experience at [kubernetes/community](https://github.com/kubernetes/community). > >/close not-planned > >[1]: https://www.kubernetes.dev/docs/guide/issue-triage/ Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes-sigs/prow](https://github.com/kubernetes-sigs/prow/issues/new?title=Prow%20issue:) repository.