Inconsistent documentation

[axalix]

What would you like to be added

1. I am following a tutorial step-by-step: https://kubernetes.io/docs/tutorials/kubernetes-basics/explore/explore-intro/

2. And right now I am on https://kubernetes.io/docs/tutorials/kubernetes-basics/deploy-app/deploy-interactive/ and started "Interactive Tutorial - Deploying an App" scenario

3. On a step 3 of a mentioned scenario you have many references to a term "pod", e.g.

• "Pods that are running inside Kubernetes are running on a private, isolated network."
• "The API server will automatically create an endpoint for each pod, based on the pod name, that is also accessible through the proxy.".
• "First we need to get the Pod name, and we'll store in the environment variable POD_NAME:"
  etc.

However pods were not yet defined or mentioned anywhere earlier in this tutorial and it is not clear what they are. In fact, you defined pods in next sections. Thus step 3 is not clear and very messy.

Why is this needed

Define "pods" earlier, so it will be clear what you are talking about or exclude / change section 3 from "Interactive Tutorial - Deploying an App" otherwise documentation looks inconsistent.

Comments

[sftim]

https://kubernetes.io/docs/tutorials/kubernetes-basics/explore/explore-intro/ defines Pods:

A Pod is a Kubernetes abstraction that represents a group of one or more application containers (such as Docker or rkt), and some shared resources for those containers

Does that cover things @axalix ?
/triage needs-information

[axalix]

@sftim The question wasn't about missing information, it was mostly about consistency.
Usually when people follow tutorials, they do it in a sequence: 1 -> 2 -> 3 -> 4
We can't use something in "1", but define it in "4".

Same here: the section "Interactive Tutorial - Deploying an App" (step #3, scenario) uses pods a lot, but they are actually defined only in next sections.

[sftim]

So, before readers encounter

Pods that are running inside Kubernetes are running on a private, isolated network

(module 2), they should have learned roughly what a Pod is.

If https://kubernetes.io/docs/tutorials/kubernetes-basics/deploy-app/deploy-intro/ outlined what a Pod is, that should cover it. Have I got that right?

[sftim]

Ok, no worries. Can you clarify the kind of change that you have in mind?

[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

[tengqm]

pls feel free to open with actionable issue details or file a new one.