No Recommendation Around Command Example in Doc Which Requires Root Privilege

[vanou]

This is a Bug Report

Problem:
In K8s doc, there are command examples which require root privilege. But there is inconsistency of use of sudo command in example (e.g. here&here with sudo but here without).

However there are pros&cons:

• Command example with sudo
  • Pro:
    1. Clear indication where root privilege is required
  • Con:
    1. dependency on tool (sudo)
• Command example without sudo
  • Pro:
    1. concise look of doc
    2. no dependency on tool
  • Con:
    1. reader who is relatively new to *nix should run commands with try&error
    2. addition of indication where root privilege is required to doc

Proposed Solution:
To add official recommendation around this to style guide.

Page to Update:
Too many pages, cannot specify here.

[aimeeu]

Thanks for creating an issue based on your #sig-docs question!

/kind feature
/sig docs
/priority important-longterm

[sftim]

What do other projects do for this?

[neolit123]

i think the best option is to include notes in relevant locations that "these commands need to be run as root" and not have sudo in the examples.

[vanou]

In terms of code snippet, it's better to include sudo, because it can be used without any modification on CLI. However simple look of no sudo is also nice.

[vanou]

I think this problem is related to style guide. And according to Style guideline on this section, topics around style guide should be discussed at SIG Docs meeting.

I'll talk about this at next meeting.

[vishakhanihore]

@vanou @aimeeu Can I work on this issue, if the issue has been already discussed in the meeting?

[vanou]

@vishakhanihore
Sorry. I haven't yet discussed it on meeting. However I'll do on next meeting (10th Dec).

And thanks for your interest.

[vanou]

I talked about this at today's meeting(2019/12/10). And I have a role to update Document Style Guide to add a guide around this issue. Discussion around this should be held at PR I'll create.

[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

[vanou]

@vishakhanihore Sorry. I don't have time to work on this issue. So, if possible, please take over this issue.

In brief, to tackle this issue

1. Determine whether to use root or not in doc by yourself
2. Claim your idea & discuss at community
3. Make consensus
4. Modify doc according to consensus

See meeting video at 2019/12/10 for what was discussed.

/remove-lifecycle stale

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