Laura's content review feedback

[lauracowen]

In general, this looks really good. I've provided a bunch of feedback and changes below but the main two things that I think need improving a little are:

• Intro (What you'll learn section) needs to be a little more focused and concise (see below).
• Switch the order of the two deployment sections (inventory and system first, then kafka; see below for why).

Here's the detail:

What you'll learn section

• What you've got isn't far off but I think it needs some slight changes to draw the focus more strongly on what is important to understand to learn anything from this guide. I think the guide is assuming the reader knows Kubernetes but not OpenShift? Is that about right?
• [x] So, remove the paragraph that starts "There are different cloud-based solutions...". Although it's a nice intro to cloud orchestration, it doesn't really explain anything that you need to know to learn from the guide. You're already assuming they know about Kubernetes and they've probably heard of OpenShift if they've come to this guide. Assume they know about cloud orchestration (or, at least, don't start there).
• [x] The paragraph starting "OpenShift is a Kubernetes-based platform..." is good - it quickly defines what OpenShift is and why you might use it. But remove the sentence "To learn..." - that's a lot of words taking up a lot of space when it's not really relevant to the guide - we're not here to sell OpenShift.
  • [x] A link to OpenShift is useful though so, instead, make the word "OpenShift" at the start of the paragraph into a link to either the docs or just to openshift.io. I'm not sure that docs page you link to is that helpful - I just found it bewildering having loads of offerings presented to me. If you want to link to the docs, be more specific - find something relevant to the guide (eg an introduction to OpenShift).
  • [x] The Operator paragraph is generally good in that it provides useful info but it's a bit long and should be probably two paragraphs at least (maybe split it just before "The Open Liberty Operator watches resources…"?).
  • [x] It also mentions custom resource definitions, which aren't introduced/defined anywhere. I think they're maybe Kubernetes concepts and you're maybe assuming the reader knows them? If so, that's ok but I think it'd be useful to at least link from first mention to the relevant page in the Kubernetes docs. eg "customer resource definitions". As it's such a key thing to understand in this guide, though, it would also be useful to very briefly define what it is here.
  • Don't mention OKD - it's not relevant to this guide. The point here is that you can use the Open Liberty Operator to deploy and manage OL apps on OpenShift clusters.
  • [x] The link to the Operators tech topic is useful, I think. But the link to the OL Operator's official documentation takes up another sentence - instead, just put the link on the first mention of "Open Liberty Operator" at the top of the paragraph. That also means they can find out that it also works on OKD if they're interested.
  • [x] Change "…including the application image, number of instances, storage settings etc. " to "…including the application image, number of instances, and storage settings." - the word "including" tells the reader that there's more than what you've listed. Adding "etc" on the end doesn't help them guess what they are so doesn't add any value to the sentence - you've listed the important ones.
  • [x] Similarly, in the sentence after change "such as Deployments, Services, Routes etc…" to "such as Deployments, Services, and Routes, …"

Additional prereqs

• [x] It's not clear how I get an OpenShift Cluster or where. The sentence about "various types of deployments…all the options" is not helpful here (it's not clear what they should do as a consequence of reading it - it needs to provide more direction). Remove that sentence and, instead, instruct them on which is the simplest cluster to create (link as closely as you can to where they should do it or, at least, the specific OpenShift docs on how to do it). Also, can they use OpenShift to create a cluster for free? Do they need to sign up or anything? Is there a trial or free option they can use to go through this guide?

Getting started

• [x] "Note that the above command MUST be run inside your OpenShift cluster; this guide assumes that all subsequent commands will be run from within the cluster." Remove "Note that" (it doesn't add anything to the sentence).
• [x] But also move this sentence to above the command. I know there are some includes used here but there's not much point providing an essential instruction after they've run the command, so see how it reads if you move that sentence to the start of the Getting started section: "Run the following command, and all subsequent commands in this guide, from inside your OpenShift cluster."

Installing section

• [x] "You see the following output:" - can you extend that slightly? "You see the following output which shows…" Just gives a bit more sense of why they need to see that output. Are these OpenLibertyApplication resources? Is that why the next sentence is relevant to this section?
• [x] "You will be making OpenLibertyApplication resources in the upcoming sections." What are OpenLibertyApplication resources? It's good that it signposts what will be coming but it's not obvious why this is relevant to know at this point - if the output is showing OpenLibertyApplication resources, it makes more sense, but that link needs to be made explicitly in the text.

Deploying Kafka

• [x] Why is the Kafka deployment done before the inventory/system deployments? The latter are far more relevant to this guide than Kafka (which is basically just a dependency in this guide - it's here to make the apps work when you run them). Can you switch the two sections round?

Deploying system and inventory apps

• [x] This is the interesting relevant bit of this guide. Don't hide it by putting loads of bumpf up-front or the reader will lose interest because it won't be clear when they get to learn something. After they've done this bit, they'll be motivated to do the Kafka deployment because they'll know that their apps won't run without it.

Scaling up section

• The green vertical line on the left of the action box is extending lower than the box. Is that correct? It looks a bit odd. Or is that to show that the update is to ad the replicas parameter? In which case, that's fine - it's still a bit odd but it makes more sense (and that's a design thing rather than the guide so don't worry about it).

[MaiHameed]

What you've got isn't far off but I think it needs some slight changes to draw the focus more strongly on what is important to understand to learn anything from this guide. I think the guide is assuming the reader knows Kubernetes but not OpenShift? Is that about right?

The focus of the guide is to show users how to use the Open Liberty Operator. It's not necessarily a focus on OpenShift, but more so that the Operator can streamline and add functionality to deployed OL apps.

A link to OpenShift is useful though so, instead, make the word "OpenShift" at the start of the paragraph into a link to either the docs or just to openshift.io.

I updated the hyperlink to go to openshift.com

Don't mention OKD - it's not relevant to this guide. The point here is that you can use the Open Liberty Operator to deploy and manage OL apps on OpenShift clusters.

The concept of the guide is to introduce Operators, and I think it's important to note that they're also deployable to OKD clusters as well as base Kubernetes clusters in the guide upfront instead of relying on them to navigate to the OL Operator page which states this.

But also move this sentence to above the command. I know there are some includes used here but there's not much point providing an essential instruction after they've run the command, so see how it reads if you move that sentence to the start of the Getting started section: "Run the following command, and all subsequent commands in this guide, from inside your OpenShift cluster."

Minor detail here, in the adoc, the Getting Started block is a pre-written insert taken from here: https://github.com/OpenLiberty/guides-common/blob/master/gitclone.adoc. I've re-written the sentence in question to after the Additional Prereqs section, but before the Getting Started header for this reason. Hopefully this works, let me know if you'd still like this changed, if so, I'll need to manually copy paste the contents of the insert.

[yeekangc]

I would say it's both OpenShift and Operators. I don't believe we are assuming that users have either knowledge or need prior knowledge of one or the other before they try the guide. And, this may become the guide for deploying onto OpenShift over time.

[lauracowen]

Don't mention OKD - it's not relevant to this guide. The point here is that you can use the Open Liberty Operator to deploy and manage OL apps on OpenShift clusters.

The concept of the guide is to introduce Operators, and I think it's important to note that they're also deployable to OKD clusters as well as base Kubernetes clusters in the guide upfront instead of relying on them to navigate to the OL Operator page which states this.

I don't really agree that it's necessary because the guide is teaching you to use the OL Operator - just what's essential to know to use it using this scenario. We have documentation (or will have) that will give you additional info. But if you want to mention OKD here, I can live with that but the guide needs to very briefly explain what it is relative to OpenShift (otherwise it just looks like an acronym that's not been defined).

[MaiHameed]

but the guide needs to very briefly explain what it is relative to OpenShift (otherwise it just looks like an acronym that's not been defined).

The sentence is currently

The Open Liberty Operator provides a method of deploying and managing Open Liberty applications on OpenShift or OKD (the community distribution of OpenShift) clusters.

Do you think OKD needs further explanation or does that look good to you?

[yeekangc]

This is not a guide about Open Liberty Operator. This is a guide for deploying on OpenShift using Open Liberty Operator. See https://github.com/OpenLiberty/guides-common/issues/411.

In my mind, the emphasis should be on OpenShift first and then Open Liberty Operator second. If we need a dedicated guide for Operators, that is a separate issue.

FYI, @gkwan-ibm.

[lauracowen]

Are we assuming they understand the basics of Kubernetes already or not though?

I'll suggests a re-draft of the intro later today but I need to know what existing knowledge we're assuming first.

[MaiHameed]

The green vertical line on the left of the action box is extending lower than the box. Is that correct? It looks a bit odd. Or is that to show that the update is to ad the replicas parameter? In which case, that's fine - it's still a bit odd but it makes more sense (and that's a design thing rather than the guide so don't worry about it).

Yes, the action block is an update action block, which is different from a create action block. The update block has the vertical green line that extends down to include the thing to update. It's a design thing and is shown in other guides as well.

[MaiHameed]

I opened a PR with the changes you requested @lauracowen, feel free to take a look and review the changes thus far. The changes are live on the lgdev site. I'll wait on your re-draft of the intro and change accordingly.

[yeekangc]

Are we assuming they understand the basics of Kubernetes already or not though?

I'll suggests a re-draft of the intro later today but I need to know what existing knowledge we're assuming first.

Basic understanding of Kubernetes is fair. The focus should be aspects specific and relevant to OpenShift than Kubernetes in general IMO. For Kubernetes itself, we can point to the Kubernetes Intro guide.

[lauracowen]

I need to finish a blog post this afternoon so depending on how long that takes, I'll also try to look at the intro again.

[lauracowen]

Okay, based on discussion with @yeekangc and @MaiHameed:

• Use the same-ish intro text as for the old openshift guide.
  • But remove the sentence “There are different cloud-based solutions for running your Kubernetes workloads.” as it doesn’t make much sense there (even in the old guide).
  • I think there still needs to be a couple of sentences towards the end of the intro (before the bit about the apps) saying that the guide uses the OL Operator and why you’d use it (why’s it better).
  • don’t introduce the OpenLibertyApplication crd in the intro at all.
• in the Installing the Operator section, give a brief intro to what the crd is at that point (where it’s mentioned - don’t need to introduce everything up front in the guide).
• the instructions for installation need to be super-simple. If it’s possible to install the operator from the web console dashboard thing in the starter account environment, just tell them to do that - don’t tell them about the CLI alternative - those instructions in the Operator github repo are awful (so much clicking to find them then about three or four steps) - nothing you can do about that but from the guide perspective, keep it as simple and frictionless as possible. don't give alternative options if at all possible.
  • if we specify that they create the cluster in OpenShift Online using the Starter (or Pro if they have it) account, the web console would work. Red Hat usually demo the dashboard for stuff like this in my limited experience.

btw, your other changes in the PR look good, thanks. btw2, if you find that the existing OpenShift guide’s instructions are clunky or confusing, flag it up and we can try to fix it rather than perpetuate the problem. That’s fine - we can improve stuff.

[MaiHameed]

23 addressed the additional comments if you could take a quick look @lauracowen. lgdev site has been updated with the latest changes

[MaiHameed]

Addressed with #23