kubernetes / website Goto Github PK

http://kubernetes.github.io/docs/user-guide/docker-cli-to-kubectl/

Viewing on Windows/Chrome, to the right of the paragraphs with inline {code} objects there are vertical scroll markers.

I'm also seeing scrollbars even when the code examples in the {pre} tags fit within the box perfectly well.

CC @CreaturesInUnitards

Currently, AFAICT, the only documentation of the format of kubeconfig is http://kubernetes.io/v1.1/docs/user-guide/kubeconfig-file.html , which provides a couple of examples and a suggestion to use the CLI to manipulate user configurations.

While this is nice as introductory material, it's insufficient as a reference for people building automation. It would be nice to have the kubeconfig format documented in the style of http://kubernetes.io/v1.1/docs/api-reference/v1/definitions.html , and the reference linked from the user guide entry.

Reduce padding in tables in API Operations docs.
Reduce font sizes so more text fits on the screen.
In the Parameters tables, give the "Description" column more width.

By API documentation, I mean:

• Operations: http://kubernetes.io/v1.1/docs/api-reference/v1/operations.html
• Definitions: http://kubernetes.io/v1.1/docs/api-reference/v1/definitions.html
• and so on for other api groups and newer versions (like 1.2)

Copied from kubernetes/kubernetes#22389

I'm guessing the best we can do for content here is porting the old HTML from the current k8s.io, so please do.

Waiting for Sara(h?) for now.

The icon for our site is blank currently. We should have stuff you can steal now from kubernetes.io. The wheel icon is fine. Higher-res is always better if you got it.

cc @CreaturesInUnitards

We have lots of presentations with good diagrams. We need similar diagrams on the site in order to help new users understand the basic concepts and the system.

cc @kmerker

I know we pointed this out in the meeting, @CreaturesInUnitards, but I'm noting this for posterity. I don't think we should launch this way.

I just copy/pasted the GitHub Blog's default syntax.css values for code syntax highlighting, and it's very black-and-red which is not necessarily the color scheme of the site. If a designer with a bit of time could tweak these values to be more on-brand (the ".highlight .s"-type classes) then that would be awesome.

Looks like it's done. The lorem ipsum is fine, we'll handle it. The layout named "headerfooter" is all set up for marketing page use, so all you should need to do is slot in the case studies instead of the docs nav, and the content body.

The non-doc CSS styles (header/footer stuff) seems very large and looks best zoomed out to about 75% in the browser.

The docs CSS styles are also big but not quite as dire, IMO; that said, they look good at 75% too.

• Port the front page from kub.unitedcreations.xyz to kubernetes.github.io repo. Looks like it's done. The lorem ipsum is fine, we'll handle it. The layout named "headerfooter" is all set up for marketing page use, so all you should need to do is slot in the case studies instead of the docs nav, and the content body.
• Remove uses of the Pi JavaScript library in favor of jQuery
• Check in your SASS partials into the repo under the folder _sass; here are instructions if this is not clear.
• CSS issue: Lists are "bumping up" against content too closely on their top margin. ex: http://kubernetes.github.io/v1.1/docs/getting-started-guides/meanstack/ and here.
• CSS issue: List spacing is very tall between top-tier items, but crowded on second tier items: http://kubernetes.github.io/v1.1/docs/user-guide/known-issues/
• CSS issue: Lists have a different font (see http://kubernetes.github.io/v1.1/docs/user-guide/known-issues/)
• CSS issue: hyperlinked/in-line code items should give users more of a hint -- suggest they at least turn blue. (See the programmatic objects in the in-page TOC http://kubernetes.github.io/v1.1/docs/getting-started-guides/meanstack/)
• CSS issue: All code examples are double-spaced. (See code examples on same page)
• CSS issue: Code examples wrap awkwardly instead of creating a scrollable area. ex: http://kubernetes.github.io/v1.1/docs/user-guide/configuring-containers/ (see line re: "false alarm" vs something like https://github.com/kubernetes/kubernetes.github.io/blob/master/v1.1/docs/user-guide/production-pods.md)
• CSS issue: Tables are completely unformatted! Scroll to bottom of this page: http://kubernetes.github.io/v1.1/docs/user-guide/jsonpath/
• CSS nice-to-have: I just copy/pasted the GitHub Blog's default syntax.css values for code syntax highlighting, and it's very black-and-red which is not necessarily the color scheme of the site. If a designer with a bit of time could tweak these values to be more on-brand (the ".highlight .s"-type classes) then that would be awesome.
• Re: The Community page: I'm guessing the best we can do for content here is porting the old HTML from the current k8s.io, so please do.
• Are we really dropping "Media" and "Events?"

e.g. http://kubernetes.github.io/v1.1/docs/getting-started-guides/docker-multinode/

Could be an issue around tables not having proper spacing?

http://kubernetes.github.io/v1.1/docs/api-reference/v1/definitions/
http://kubernetes.github.io/v1.1/docs/api-reference/v1/operations/

Lots of instances where tables/headings are bumping against each other.

In other refdoc news, I know we talked about making the code examples scroll, but check out what's going on in the man pages for the CLI:

http://kubernetes.github.io/v1.1/docs/admin/kube-apiserver/

Is there a graceful way to line wrap with indenting -- just in this one case? If too gnarly, no worries.
cc @CreaturesInUnitards

http://kubernetes.github.io/docs/search/?q=nodes

Too much whitespace, results not aligned with header.

@CreaturesInUnitards

By API documentation, I mean http://kubernetes.io/v1.1/docs/api-reference/v1/operations.html and the corresponding pages for 1.2, once that is branched, and also http://kubernetes.io/v1.1/docs/api-reference/v1/definitions.html.

Don't have the k8s.io nav sidebar when viewing docs. The docs need their own nav sidebar, since docs are so long. If possible, extract all the h3's from the html and generate a sidebar with a list of those topics. If that isn't practical, then just get rid of the sidebar as it isn't helping.

Also, don't have the k8s.io top nav bar when viewing docs. If the person has found the API docs, they probably already are comfortable navigating other K8s.io documentation and don't need the top nav bar.

Copied from kubernetes/kubernetes#22389

Scroll to bottom of this page: http://kubernetes.github.io/v1.1/docs/user-guide/jsonpath/

ex: http://kubernetes.github.io/v1.1/docs/getting-started-guides/meanstack/ and here.

http://kubernetes.github.io/docs/getting-started-guides/coreos/azure/

Either make the footer about the same size as the sticky top menu bar, or don't have it be sticky. It's repeated on every page, so frankly I'd go with the latter.

We used to have dots in the right-margin that linked to the various sections of the homepage. Those seem to be gone.

We don't really document how to use watch, and what we do have in api-conventions.md is out of date.

@lavalamp @smarterclayton

b/c 16x16 is so passe.

http://kubernetes.github.io/v1.1/docs/user-guide/known-issues/

seems like it should center...?

Our events calendar:

Embed source:
<iframe src="https://calendar.google.com/calendar/embed?src=nt2tcnbtbied3l6gi2h29slvc0%40group.calendar.google.com&ctz=America/Los_Angeles" style="border: 0" width="800" height="600" frameborder="0" scrolling="no"></iframe>

Link:
https://calendar.google.com/calendar/embed?src=nt2tcnbtbied3l6gi2h29slvc0%40group.calendar.google.com

cc @CreaturesInUnitards