Present platform-specific commands appropriately about guide-kubernetes-intro HOT 7 CLOSED

I laid out my ideas for how to solve this issue in #29 , let me know what you think.

from guide-kubernetes-intro.

Tagging @cajaygle @megmulsy @lauracowen if they have thoughts. @kinueng @mbroz2 @gcharters @NottyCode, FYI and your feedback welcome too.

The team will work out options given what we have and share them ASAP.

from guide-kubernetes-intro.

I think #29 (comment) is suggesting we have a single code block with selectable tabs on top. The tabs would be labeled as "Windows, Unix, ..." and a reader can click one of the tabs to show the platform specific command.

If we want a code block with tabs, we will need to write an Asciidoc extension to support tabs since Asciidoc does not have native tabs support.

from guide-kubernetes-intro.

@kinueng, that is an idea or an option. We don't have a decision on that yet and I will suggest for @cajaygle and @megmulsy to consider what will be the appropriate design for this using the Kube and Istio guides as the basis.

In the mean time, we are moving forward to try to wrap the Kube and Istio guides with what we have today -- with Asciidoc as-is; granted they must be consumable -- and any visual or design improvements can come later (as part of multi-pane layout).

There is other design issue to consider for these 2 guides too: There isn't too many code snippets or classes in them. So, in a multi-pane layout, we pretty much have a unused pane.

from guide-kubernetes-intro.

I also feel that having a single box with the platform-appropriate command would be the best. we can auto-detect their platform, and at the beginning of the guide or first appearance of a platform-specific command we tell them we've auto-detected their platform and give them the option to change it. then all subsequent instructions would use that platform to display the appropriate command. if we did that then maybe we wouldn't need a selection mechanism for each command block, or that may still be useful to include on each.

from guide-kubernetes-intro.

One thing to keep in mind is that it may not be only the commands that change. You may want slightly different instructions as well. For example, in this guide we need to run minikube start for one platform, and for another platform we tell them to go to their settings and check a box. We could probably write them in a way such that only the commands change, but it would be more flexible to take into account that some instructions may change as well.

from guide-kubernetes-intro.

I think we're done with this issue with the current guide(s).

from guide-kubernetes-intro.