If move the Nice Work! out from the "Summary" page, better rename it to "Clean up your environment"

The convertor generates PR to the staging or master branch. Suggest to add a prefix for the PR title as following:

• To staging: Change to cloud-hosted-guide-cdi-intro
• To master: Change to cloud-hosted-guide-cdi-intro

The docker output doesn't match with the one in the guides. We need a way to switch these to the output that will match the one that the user sees in their terminals

Once Skills Network comes up with a permanent fix for the issue where underscores are being changed to italic writing (even when escaped) We will have to change the GuideConverter. This included removing the hard coded temp fix and adding a function to add the permanent fix.

In the content, if word has underscore characters, they are removed,

e.g. io_openliberty_guides_inventory_inMaintenance is shown as ioopenlibertyguidesinventoryinMaintenance

See the code and the first statement under the code

issue was found in https://openliberty.skillsnetwork.site/quicklab/cloud-hosted-guide-microprofile-config-staging

Step 9

Consider having "Navigate to the target directory" on its own line so that its clearer or add a cd command to the target directory

Overall
The text surrounding the curl statements need to be revised. The guide itself worked as expected.

When display the xml, need to hide the tag:: and end:: comments

<!-- tag::featureManager[] -->
<!-- end::featureManager[] -->

for java

// tag::getProperties[]
// end::getProperties[]

See https://openliberty.skillsnetwork.site/quicklab/cloud-hosted-guide-rest-intro-staging

When trying to copy the new code from the left pane into the editor on the right, the error message pops up:

I am able to successfully copy and paste into the terminal, the issue is only with the editor. Also, if I copy using the browser's copy and paste, it works fine.

This was tested on a Linux VM using Firefox. This could be an issue unique to testing on a VM, but this is my only way to test it.

Got invalid markdown instructions when run the following in staging SN:

• cloud-hosted-guide-rest-intro
• cloud-hosted-guide-containerize
• cloud-hosted-guide-microprofile-config
• cloud-hosted-guide-microprofile-fallback
• cloud-hosted-guide-microprofile-rest-client
• cloud-hosted-getting-started

In the following statement, the "Git repository" should have a link to the guide repo.

"The fastest way to work through this guide is to clone the Git repository and use the projects that are provided inside:"

[File -> Open]guide-cdi-intro/start/src/main/java/io/openliberty/guides/inventory/InventoryManager.java is clear to readers

Suggest:
Run menu: File > New File
File path: /home/project/guide-cdi-intro/start/src/main/java/io/openliberty/guides/inventory/InventoryManager.java

For Replace or Update instruction:
Run menu: File > Open...
File path: /home/project/guide-cdi-intro/start/src/main/java/io/openliberty/guides/inventory/InventoryManager.java

Tested using login with Github, failed with:

An error occurred when signing you in to Open Liberty Hands On.
We are sorry, you are not authorized to access Open Liberty Hands On via this channel. Please contact your learning administrator or manager in order to access Open Liberty Hands On.

Error Details:
Authentication process cancelled

Retried log in with LinkedIn. This succeeds. Both my LinkedIn and Github are registered under the same e-mail address though.

Tested on Windows 10 on Firefox

Step 1

• CDI link appears to be duplicated, appearing twice, with the second instance overwriting what should be a link to a blog post for the RestClientBuilder.

Step 2

• In message The defaultServer server is ready to run a smarter planet., the word "is" is bolded for some reason.
• When it asks you to point the browser to a URL, this isn't applicable for the cloud hosted guides
  • Previously mentioned in #53
  • Perhaps mentions of localhost:9080 can be replaced with something like austinseto-9080.theiadocker-24.proxy.cognitiveclas.ai (the URL I had) or similar?
  • curl command cannot be used before opening another terminal as the application is running the first terminal
• Descriptions of URLs have parts of the URL italicized for some reason
• Unsure if statement about FQDN is applicable on the cloud hosted guides

Step 3

• In example message Press the Enter key to run tests on demand the word "press" is bolded and "on" is highlighted

Step 6

• It says to "select either approach" but no approaches are shown

Step 7

• In description of testDefaultLocalHost() the URL has a backslash at the start

Step 8

• Hyperlink for Hostname with verification... is duplicated, overwriting the hyperlink MicroProfile Rest Client specification that appears on openliberty.io

the command curl http://localhost:9080/inventory/systems has no copy icon and having {: codeblock}

As pointed out by @griffinhadfield there is no need for a docker start include. This is because docker is already started up.

At the moment the GuideConverter removes the image and the reference to that image. Would be good checking how images would look on SNL. If they look okay, it might be worth getting the GuideConverter to keep the images. instead.

1. change a guide and merge a PR
2. the converter create a PR on the quick-labs repo, but not merge
3. another change for the same guide at step 1, and merge the PR
4. the converter should override the PR at step 2 correctly

The above should be applied to the staging and master

Change "Log out" to "log out"

"Now Log out by navigating to: "

At step 1, there is a long and weird url

Step 2

• Missing the getting started part (open terminal + git clone etc)

Step 4

• Link doesn't match the guide http://localhost:9081/inventory/systems/pass:c[[system-ip-address]] -> http://localhost:9081/inventory/systems/[system-ip-address]
• There should be a curl command associated to that link
• problem here as well http://localhost:9081/inventory/systems[http://localhost:9081/inventory/systems^]

Step 5

• same thing here, http://localhost:9081/inventory/systems/pass:c[[system-ip-address]] -> http://localhost:9081/inventory/systems/[system-ip-address]
• and we should also add a curl associated with that link

Step 6

• can't go to step 7?

Step 7

End to end works!

https://raw.githubusercontent.com/OpenLiberty/quick-labs/cloud-hosted-guide-cdi-intro/staging/instructions/cloud-hosted-guide-cdi-intro/instructions.md

At ## What you'll learn section, the following url is not right
[Creating a RESTful web service](https://openliberty.io/guides/restintro.html)

It should be https://openliberty.io/guides/rest-intro.html

Some commands will be giving different outputs for users when using the build in environment. We can add this to the guide Converter by running commands and finding the different outputs and then adding these outputs to the cloud-hosted file of Guides-common. Then switch the outcomes when the converter finds an output that should be different

Step 2 of 10

Should ask for users to open a new terminal before prompting the curl commands

Step of 10

Issue with parsing the property name:

Step 5 of 10

Suggestion to change Note that three default config sources mentioned **above** are static and fixed on application... to
Note that three default config sources mentioned **in the previous step** are static and fixed on application... or something similar

Property names not parsed correctly:

Step 6 of 10

Step 8 of 10

Step 9 of 10

Login and log out was working properly. Integration test passed. End to end works as expected too.

https://raw.githubusercontent.com/OpenLiberty/quick-labs/cloud-hosted-guide-cdi-intro/staging/instructions/cloud-hosted-guide-cdi-intro/instructions.md

Under ### Try what you'll build, looks not good
see

Tested using login with LinkedIn

Tested on Windows 10 on Firefox

General

• When the user is asked to create/modify certain files, the highlighting appears to miss package

Step 1

• The link to the guide-rest-intro links to the guide on openliberty.io, unsure if intended or if these links are intended to link to the guides on the cloud hosted platform

Step 2

• When it asks you to point the browser to a URL, this isn't applicable for the cloud hosted guides
  • Perhaps mentions of localhost:9080 can be replaced with something like austinseto-9080.theiadocker-8.proxy.cognitiveclas.ai (the URL I had) or similar?
  • curl command cannot be used before opening another terminal as the application is running the first terminal

Step 4

• The URLs displayed are incorrect (besides previously noted issue regarding localhost)
  • Only 1 URL is listed (guide on openliberty.io lists 2 URLs)
  • Random dash appears instead, I think URL got cut off or similar, excerpt copy pasted below

Excerpt:

You can find the inventory and system services at the following URLs:

curl http://localhost:9080/inventory/systems

The curl command function should be revisited and re written in a better way or, overall switched over to using the build in environment UI

• the mvn commands area does not have the copy icon
• there is {: codeblock) at the end

As shown in issue #56 , it might be worth it to look into creating a method for the GuideConverter to create different curl commands depending on some conditions.

The first curl command after new terminal instructions is set up incorrectly, instead of

curl ...

{: codeblock}

it becomes

curl ...

: codeblock

If SN ever supports ISTIO the guide converter will need to have added functionality to remove the beginning of the bellow text. Also will have to transform the first one into a command with a copy button

Should ask users to log out the lab when finish at the last "Summary" step?

e.g. add a statement
Log out by running [Account -> Logout]

Otherwise, in case users not complete a lab and open another lab, SN will open the same env, it may cause problem

Can users have multiple cloud-hosted guides opened at the same time?

If so, how can they effectively work with multiple cloud-hosted guides at the same time with the same hosted environment? (Open multiple terminals?)

Should clarify and provide guidance on this where appropriate.

I can see users wanting to reference multiple guides and try them out together. May be not common or day 1 usage but can happen. At least, we should allow for it.

On the Skills Network Labs draft website:
Note: not sure if this is where to open up an issue

Step 1 of 8

• Localhost link has a slash in front:

Step 2 of 8

• We should prompt the user to open a new terminal in order to run the curl command

Step 5 of 8

• We shouldn't keep adoc tags in the xml config file

Step 7 of 8

• Has a misplaced curl command

Otherwise, log in works and end to end application works as well.

• instruction can be

cd /home/project
rm -fr guide-cdi-intro

• "Great work! You're done!" -> "Nice work!"

rm -fr cloud-hostedguide-getting-started is not right

It should be rm -fr guide-getting-started

Need to insert some instruction how to start.
Readers don’t know where to run the git clone ... at step 2

e.g. Run menu [Terminal] > [New Terminal]. At the terminal console run the following commands:

When it asks user to point the browser to a URL, this isn't applicable for the cloud hosted guides
Perhaps mentions of localhost:9080 can be replaced with something like jakubpomykala-9080.theiadocker-8.proxy.cognitiveclas.ai or similar?

Step 6

[File -> Open]guide-getting-started/start/src/main/java/io/openliberty/sample/system/SystemReadinessCheck.java
and
[File -> Open]guide-getting-started/start/src/main/java/io/openliberty/sample/system/SystemLivenessCheck.java

should be

[File -> New File]
guide-getting-started/start/src/main/java/io/openliberty/sample/system/SystemReadinessCheck.java

and

[File -> New File]
guide-getting-started/start/src/main/java/io/openliberty/sample/system/SystemLivenessCheck.java

Step 7

[File -> Open]guide-getting-started/start/src/main/liberty/config/server.xml
to

[File -> Open...]
guide-getting-started/start/src/main/liberty/config/server.xml

Now is showing
[File -> Open]guide-getting-started/start/src/main/liberty/config/server.xml

Suggest to be in two lines and have ... after Open to match what I see for VS code

[File -> Open...]
guide-getting-started/start/src/main/liberty/config/server.xml

or

[File] > [Open...]
guide-getting-started/start/src/main/liberty/config/server.xml

It is not right only have 1 step.

The last step of the cloud-hosted-guide-getting-started has the logout instruction but not the cloud-hosted-guide-cdi-intro

See the last step of https://openliberty.skillsnetwork.site/quicklab/cloud-hosted-guide-microprofile-rest-client-staging. The following text should be before the clean up instruction

MicroProfile Rest Client also provides a uniform way to configure SSL for the client. You can learn more in the Hostname verification with SSL on Open Liberty and MicroProfile Rest Client blog and the Hostname verification with SSL on Open Liberty and MicroProfile Rest Client.

Feel free to try one of the related guides where you can learn more technologies and expand on what you built here.

• Order the "Nice work!" section first i.e. summarize what the users have learnt first

• Improve and/or clarify the relevance and why for "Clean up your environment"

  • Why do we need to clean up? Can the steps be automated?
  • Logout: Do we need to log out if users want to try more guides?

• Link back to https://openliberty.io/guides and/or relevant guides

@gkwan-ibm @jamiecoleman92

It appears that we program the conversion logic in code.

Can we consider a more template-based approach? And, are there tools that can help in such regards with AsciiDoc to MD conversion?

@jamiecoleman92 @gkwan-ibm

Step 5

• The code block is commented out

Step 2

• The following should be reworded and we should also prompt the user to open another terminal before prompting them to curl.

• start should be changed to finish

• parsing issue

• Same thing here; start should be changed to finish, the parsing issue also happens after this curl command

Step 5

• Should reword the following:

• Add a curl -k -u admin https://localhost:9443/metrics/application command which prompts users to enter the adminpwd password

• This issue happens a couple times in this step:

• Wording here should be changed because we are using curl as opposed to using the browser

• Wording here should be changed as well.
• The -I flag should be added to the command so that the status code shows up ie. curl -I http://localhost:9080/system/properties

HTTP/1.1 503 Service Unavailable
X-Powered-By: Servlet/4.0
Date: Tue, 12 Jan 2021 00:28:55 GMT
Content-Length: 0
Content-Language: en-US
Connection: Close

• Missing a curl -k -u admin https://localhost:9443/metrics/application

Step 6

• The integration test code has comments that are not well formed which causes errors

The application works, integration test passed when I copied the code from the draft site and log in also works!

Functionally, everything works well in the guide. I have a couple pieces of feedback regarding the content:

• I think that the way the user is instructed to run the curl commands could be worded better. For example, the first time the user is asked to run the command, it is phrased as such:

To access the system microservice, see the 

`curl http://localhost:9080/system/properties`

URL, and you see a list of the various system properties of your JVM: ...

Im not sure it makes sense to say "see the" followed by a command. Consider replacing it with something like:

Open a new tab of your command-line session and run the following command to access the system microservice:

`curl http://localhost:9080/system/properties`

You should see a list of the various system properties of your JVM: ...

I think the instructions preceding the curl commands should be reworded throughout the guide if possible.

• In step 8/10, the section still contains the instructions to make sure Docker is installed and to start the daemon. I don't think this applies for the cloud hosted labs because it's already set up.

Pending on OpenLiberty/guides-common#562, the guide content will provide 2 sets. The converter should show the cloud-hosted content.

e.g.

• show the cloud-hosted content provided by the guide instead of converting the url link to curl <url>
• a better way to resolve #15

In original guide when there is an import code file command, sometimes it includes hide_tags=. It will be good to add this to the guide converter by using regex to find what tag within file needs to be hidden and then again using regex delete that tag from the code snippet

Create links to the labs defined by the :page-related-guides: attribute in README.adoc

Instead of "Check you are in the home/project folder:", it is better to ask users change to the project directory cd /home/project