New v1.1 navigation menu #16143

RichieEscarez · 2015-10-23T04:23:10Z

The nav menu includes the new and previously missing topics, see it in my fork: http://richieescarez.github.io/kubernetes/v1.1/index.html

In this PR I also have also:

integrated this new nav menu into docwithnav.html template (so all files that we push into the _v1.1 folder in gh-pages will be build with this nav menu)
included new v1.1 copies of the landing pages (which now all contain short descriptions (attempt to improve SEO))
see specific details below

Please review the following changes to ensure they have been located correctly in the menu.

IMPORTANT: we have not run the scripts to generate the .html files nor have they been copied into the new _v1.1 folder in gh-pages. Therefore no topics will show when you click in the nav menu.
QUESTION Can someone help run that script so that we can test the doc set out on k8s.io? (it will publish the content but nobody will know it there unless they manually change their URLs for .../v1.0x/... to .../v1.1/...) thanks @krousey !

Attn:
@caesarxuchao, @nikhiljindal, @krousey, @thockin, @bprashanth, @jszczepkowski, @erictune
Please see the location of your documents below and provide feedback on what needs to change (is anything missing? are the URLs correct?).

Notable changes:

New "adv topics" landing page (please click link and review all, including short description): http://richieescarez.github.io/kubernetes/v1.1/advancedtopics.html
The App. Admin. section was moved around a litte. I also removed from the menu and instead inserted mention of a "quick walkthrough" in the landing page of the "detailed walkthrough":
- Review "detailed walkthrough" landing page (and new short descriptions): http://richieescarez.github.io/kubernetes/v1.1/app-admin-detailed.html
- Moved: "Quick Start" Inserted: "prereqs" "compute resources"
  - Indented DNS and OVS:
Added "Extensions API" content: http://richieescarez.github.io/kubernetes/v1.1/api-ref.html
Revised title: Added "installing" to our "Getting Started" topic title (SEO recommendation)
Review these new short descriptions in the landing pages (SEO recommendation):
Added/Inserted the following topics (none of these were perviously linked to the nav but other topics point to and open them (so they should appear in the nav to show context)):
- "life of pod" "firewalls" and "PV"
- all three sub topics
- "security context" "config best practices"
- "accessing the cluster" "service accounts" "etcd"
- "kubeconfig" "sharing cluster access" "Garbage collection"
- Under Examples: "resource quotas" "setting CPU/mem limits"
- "jsonpath" "all the kubectl commands" "kubectl for docker users" "release roadmap"

Fixes #15903
Related #15893

k8s-github-robot · 2015-10-23T04:48:54Z

Labelling this PR as size/XL

bgrant0607 · 2015-10-23T17:09:41Z

We need to distinguish between menu selections that expand into more items in the menu bar and those that change the content on the RHS.

bgrant0607 · 2015-10-23T17:27:27Z

I'm going to make a bunch of comments, but have a meeting shortly. If you have other things to do, you might want to wait for more feedback.

One thing discussed over IM: I don't like "Advanced Topics". These are really "New Features". Other issues with that menu and page:

All the APIs are part of the "extensions" API group currently, including Ingress. I don't see why that is called out differently.
Ingress, Job, and Horizontal Pod Autoscaling are all beta and available by default.
DaemonSet and Deployment are disabled by default. Although they are reachable via /apis/extensions/v1beta1, they are NOT beta.

RichieEscarez · 2015-10-23T17:34:56Z

Thanks @bgrant0607 , i will look into adding chevrons for container topics (that open sub-menus).

Sorry, I understood that the ingress resource was actually apart of core but ill move them all together.

The alpha items/topics should explicitly call out that they are alpha (as mentioned in discussions with dev owners). Should we try to call them out in the nav menu too? I was trying to avoid mentioning both alpha and beta all together.

bgrant0607 · 2015-10-23T17:53:59Z

"Overview and concepts" should not be the first subgroup under "User's Guide". Ingress, Job, and Horizontal Pod Autoscaling should be added to that subgroup.

Also, "Architecture" doesn't belong under "Overview and concepts". It belongs under Cluster Administration.

bgrant0607 · 2015-10-23T18:03:36Z

Put docs/user-guide/overview.html under Getting Started.

Put the concept list under Application Administration > Overview and concepts.

bgrant0607 · 2015-10-23T18:07:50Z

Take Life of a Pod and Firewalls out of the concept list. Don't indent Persistent Volumes, as it looks out of place.

bgrant0607 · 2015-10-23T18:15:33Z

Remove "Kubernetes Basics" from Tutorials.

Rename "Deploying Clusters" to "Deploying Clustered Applications". It's longer, but "Clusters" is ambiguous with Kubernetes clusters.

bgrant0607 · 2015-10-23T18:15:50Z

Or maybe just "Clustered Applications"

bgrant0607 · 2015-10-23T18:16:49Z

"Persistent Images" is incorrect terminology. It should be "Persistent Volumes".

bgrant0607 · 2015-10-23T18:18:20Z

Put JSONPath under CLI Reference.

bgrant0607 · 2015-10-23T18:21:57Z

The difference between "Overview" and "kubectl" is not clear. I suggest "Command Reference" for the latter.

bgrant0607 · 2015-10-23T18:23:48Z

Done with my current round of comments.

RichieEscarez · 2015-10-23T18:51:30Z

Ok thanks. Ill be offline for awhile and will recover these later today.

I just pushed these sub menu indicators (carets), PTAL:

bgrant0607 · 2015-10-23T22:05:06Z

The carets help a lot, thanks.

RichieEscarez · 2015-10-24T19:12:23Z

Implemented all request/suggested changes (see list below for deviations/notes)
Note: docs copied in from master so we can test the actual links now

Other notable changes:

Fixed carets: moved to the left side (to avoid weird wrapping, see screen cap below)
Removed sub section: "Adv topics" (our "extensions" topics were all moved under app admin concepts)
Remove "life of a pod" and "firewalls" (neither are connected to the nav menu - user wont see their location when viewing those topics):
`
The Life of A Pod
Firewalls
Moved "k8s basics tutorials" into App. Admin. section: "Quick Walkthrough: Kubernetes Basics"
Added section/titles to app admin (to organize and improve scanability/retrievability):

Note: Something to track is that these links do not work yet:
Deployments
Ingress Resources
Horizontal Pod Autoscaling

RichieEscarez · 2015-10-24T19:15:30Z

_layouts/docwithnav.html

@@ -16,7 +16,12 @@
 	<div class="row">
 		<!-- Navigation menu -->
 		<div class="col-md-3 hidden-sm hidden-xs" id="wrapper">
-			{% include nav_v1.0.html %}
+			{% case page.collection %}


this adds new _v1.1 content into the build and specifies what version of the nav menus to use per "collection" (ie _v1.0 or _v1.1)

RichieEscarez · 2015-10-24T19:20:07Z

@bgrant0607 PTAL

…tegrate new doc set into docwithnav.html template, and included new copies of the landing pages (that contain short descriptions) Fixes kubernetes#15903

k8s-github-robot · 2015-10-26T13:38:17Z

@k8s-bot ok to test

pr builder appears to be missing, activating due to 'lgtm' label.

k8s-github-robot · 2015-10-26T13:38:19Z

Continuous integration appears to have missed, closing and re-opening to trigger it

k8s-github-robot · 2015-10-26T14:08:03Z

@k8s-bot ok to test

pr builder appears to be missing, activating due to 'lgtm' label.

k8s-github-robot · 2015-10-26T14:08:05Z

Continuous integration appears to have missed, closing and re-opening to trigger it

k8s-github-robot · 2015-10-26T14:38:07Z

@k8s-bot ok to test

pr builder appears to be missing, activating due to 'lgtm' label.

k8s-github-robot · 2015-10-26T14:38:09Z

Continuous integration appears to have missed, closing and re-opening to trigger it

k8s-github-robot · 2015-10-26T15:10:05Z

@k8s-bot ok to test

pr builder appears to be missing, activating due to 'lgtm' label.

k8s-github-robot · 2015-10-26T15:10:07Z

Continuous integration appears to have missed, closing and re-opening to trigger it

k8s-github-robot · 2015-10-26T15:44:21Z

@k8s-bot ok to test

pr builder appears to be missing, activating due to 'lgtm' label.

k8s-github-robot · 2015-10-26T15:44:23Z

Continuous integration appears to have missed, closing and re-opening to trigger it

wojtek-t · 2015-10-26T15:47:06Z

@RichieEscarez @k8s-oncall

There seem to be some problem with this PR - we cannot start any tests for it.

krousey · 2015-10-26T15:52:35Z

@wojtek-t This branch has no tests.

k8s-github-robot · 2015-10-26T16:16:02Z

@k8s-bot ok to test

pr builder appears to be missing, activating due to 'lgtm' label.

k8s-github-robot · 2015-10-26T16:16:04Z

Continuous integration appears to have missed, closing and re-opening to trigger it

brendandburns · 2015-10-26T16:39:36Z

manually merging because merge bot is broken.

New v1.1 navigation menu

RichieEscarez added the kind/documentation Categorizes issue or PR as related to documentation. label Oct 23, 2015

RichieEscarez assigned bgrant0607 Oct 23, 2015

RichieEscarez added this to the v1.1 milestone Oct 23, 2015

googlebot added the cla: yes label Oct 23, 2015

RichieEscarez force-pushed the newv11navmenu branch from 3ee103f to a247f4f Compare October 23, 2015 04:33

k8s-github-robot added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Oct 23, 2015

RichieEscarez reviewed Oct 24, 2015
View reviewed changes

RichieEscarez force-pushed the newv11navmenu branch from cc10b7d to 517c2f0 Compare October 24, 2015 19:19

RichieEscarez force-pushed the newv11navmenu branch from 517c2f0 to a628d4c Compare October 24, 2015 19:20

New v1.1 navigation menu (with new and previously missing topics), in…

a603ab4

…tegrate new doc set into docwithnav.html template, and included new copies of the landing pages (that contain short descriptions) Fixes kubernetes#15903