Need consistency regarding Docker prereq in guides

[mbroz2]

Lots of the guides now use Docker, but it's not listed in the Prereqs section. Instead, different guides mention to install docker in various ways under various sections in the Toc, for example: containerize guide has a link to install docker in the 'Building your docker images' section microshed has it in 'What you'll learn/what is docker?' istio has an 'additional prereqs' section with different tabs on installing docker for each os

Instead, add Docker to the "Prereqs" section and either link to Docker documentation or our own within the guide, like the 'additional prereqs' section in istio.

[yeekangc]

Tagging @gkwan-ibm @lauracowen @mdenby @cajaygle for their thoughts.

[lauracowen]

I think it makes sense to add it as a prereq if it's required to do the guide. And having Docker installation consistently handled across the guides would be good.

[jj-zhang]

Dockers need to be updated:

• [x] guide-getting-started
  • https://github.com/OpenLiberty/guide-getting-started/pull/184
• [x] guide-docker
  • https://github.com/OpenLiberty/guide-docker/pull/79
• [x] guide-containerize
  • https://github.com/OpenLiberty/guide-containerize/pull/42
• [x] guide-microshed-testing
  • https://github.com/OpenLiberty/guide-microshed-testing/pull/51
• [x] guide-spring-boot
  • https://github.com/OpenLiberty/guide-spring-boot/pull/56

[gkwan-ibm]

@mbroz2 @lauracowen @yeekangc I'd like to confirm with you whether it is ok or not to have the Additional Prereq section in the Getting Started guide. It means readers have to install Docker before continue. I just have a thought that "Will it scare the readers to run the getting started guide?" Now (no additional prereq), readers will run the guide until the last 2 sections, if they don't want to run docker, they can skip.

[yeekangc]

In general, I see Additional Prereqs as the exception rather than the norm. Most guides shouldn't need Docker.

For the Getting Started guide, I would think we should not indicate Docker as required. It should be optional. I am fine if we indicate in the initial section that if you want to try these sections, you will need Docker but it's optional for the rest or until then.

[lauracowen]

I think that the way the GS guide does it now is fine. And any other guides where Docker is just an extra bit, that would be fine too. Whereas for guides where Docker is essential (eg the containerizing guide), it has to be in the pre-reqs list.

I don't think I have a massive problem with having the |Docker| button on the top-right as part of the normal Pre-reqs list for all guides that use Docker. But I'm not sure it's necessary. And it could look like Docker is required to do any part of the guide - which we really don't want because it could put people off even bothering to do the guide.

I think we, as authors of the guides, should have guidance about how to indicate Docker prereqs when we write guides (and some degree of consistency will help that) but I don't think users coming to the guides will care that much about whether one guide says it one way or another. Once they've installed it once, they will just ignore mention of installing Docker no matter how it's presented.

I'm not really sure on the rationale for having the Additional Prereqs section at all - other than that the Istio guide has different pre-reqs per OS? Is that the reason? I don't like the idea of it because it's more stuff up-front that's not part of the guide itself.

[gkwan-ibm]

In https://github.com/OpenLiberty/guides-common/issues/363#issuecomment-639122571, we identified the guides need Docker but don't have the Additional Prereq section for Docker. The docker, containerize, and mst guides are reasonable to ask readers to install Docker, so we will continue to make the change. But, we will leave the getting started and the spring-boot guides.

[gkwan-ibm]

close

• the docker, containerize, and mst guides were updated