Update project source with build.gradle and provide instructions on how to build the project using Gradle as an alternative to Maven.

Consider #116 as part of this work.

Guide on how to use the configureArquillian task in liberty-gradle-plugin and configure-arquillian goal in liberty-maven-plugin, as well as the Arquillian Liberty dependency bundles, with Arquillian Liberty Managed 1.0.0.Final (pending release).

LATEST and RELEASE version numbers don't make any different as of yet (since only GM guilds are pushed into the Maven repo), but we should stick to using RELEASE just in case this changes in the future.

So, lets make sure we're using RELEASE in all of the guides and that this versions works (ie. run the tests to verify).

Current guides not using RELEASE (this is based on whats currently on the dev site):

Please change the version tag to RELEASE in your pom.xml (this includes under start and under finish!!!):

<groupId>io.openliberty</groupId>
<artifactId>openliberty-runtime</artifactId>
<version>LATEST</version>

Introduction to the popular Apache logging framework Log4j, and learn how to add logs to your Open Liberty applications using Log4j

Write a guide for MicroProfile Metrics.

Building fault tolerant microservices with the @CIRCUITBREAKER annotation

This is to review the static MP config guide, in plan for iteration 18.4. Info to be added.

I wanted to touch base about the guides descriptions on the Open Liberty All Guides page (openliberty.io/guides)

I’ve noticed that most of these descriptions just echo exactly what is said in the title, instead of giving additional information to the user to help them decide whether or not this particular guide is what they need (see examples below)

The descriptive titles are a great start, but the descriptions should be edited to make this second level of info more useful for users. Taking out the repetition of ‘Learn how’ would help as well - finding new ways to phrase what the content contains.

I’d like to strive toward something more like this that gives a user more info - The following is a better example of what's out there currently.

Thanks!
Megan Mulholland - Open Liberty Design Team
(I'm also @megmulsy on slack)

Guide for building web application with JSF.

Guide for processing form data in a JAX-RS service.

Create a guide for MicroProfile Healthchecks.

Create a guide that walks you through how you can consume REST services as a client on Open Liberty

Create an OL guide for building with Gradle.

Need some 'how to' info on how to contribute a guide to Open Liberty.

Maarten has suggested a JPA guide and has asked for such guidance soon: see https://twitter.com/mthmulders/status/919927099917586434 and https://twitter.com/mthmulders/status/923162136427356160

See project structure on https://github.com/OpenLiberty/guides-common/wiki/Getting-started for how to structure your project. We’re using a new structure from today. We need to refactor the guides.

Create a guide on how to use MicroProfile Config.

The sentence on the "contribute to this guide" page uses incorrect grammar - "Is something missing or needs to be fixed?" The subject is "something" and the verb is "is" which makes it "something is missing" and "something is needs" - should be "needing". This is used throughout interactive and static guides.

OpenLiberty/iguides-common#98 is the same

Create a guide on how to use MicroProfile OpenTracing.

Guide on how to use the configureArquillian task in liberty-gradle-plugin and configure-arquillian goal in liberty-maven-plugin, as well as the Arquillian Liberty dependency bundles, with Arquillian Liberty Remote 1.0.0.Final (pending release).

Review the currently published guides and identify anything that should be improved.

For example, consider if we should have diagrams as part of introduction to better illustrate what the guides and/or the samples will talk about. Or, any reorganization or structure improvements that we should do.

• Creating JAX-RS
• Maven
• MicroProfile Intro
• HATEOAS
• Multi-Modules
• CORS
• Consuming REST from Java
• Consuming REST from AngularJS

Write an introductory guide for developing with Open Liberty Tools.

We should have automated testing for the code assets of the guides e.g. what's under /finish of the guide repos to ensure that they continue to work on new levels of OL and to catch any regression or issue.

The work should mostly be defining and setting up the infrastructure. We should be able to reuse the JUnit tests in each of the guide as the tests to run. Should review test coverage though.

We need to work out when to update all the sample apps/code assets to use new feature versions. Annually? Every release?

Using MicroProfile Config for static configuration injection

Create a guide on how to use MicroProfile OpenAPI.

Create a guide that walk you through how to work with multiple modules and assemble them using Maven on Open Liberty

My usability tester (relatively new to Java language) found it confusing that the little Java snippets that happened not to have any coloured syntax highlighting in them look a lot like something that should be entered on the command line; for example:

I propose that we should at least have the snippet box display a shell prompt on snippets that should be entered on the command line (but that shell prompt must not be copyable by the Copy button, and should have enough space between it and the start of the command that people swiping to copy don't accidentally copy it):

In addition, can we consider slightly different look-and-feel for the background of code snippets that are to be displayed for illustrative/explanatory purposes (no copy button) vs snippets that are displayed to be copied (and have the copy button). Just a visual cue that could be really subtle but perceptually noticeable; eg a lighter shade of grey or something.

In sum, we have three (or maybe four - see update below) types of snippets to display:

• Java (or other) code that has a copy button and the user is expected to copy and paste that code into a text editor to be compiled/run.
• Java (or other code) that does not have a copy button and the user is not expected to do anything with it. Its purpose is to highlight parts of previously copied code as part of an explanation of what that code does.
• Commands to be run at a command line/terminal prompt and should have the copy button on them.

I think we need the three to be more visually differentiated.

Update: There might be a good argument for having a fourth differentiated snippet: displaying output from a command or console action etc.

Guide on working with Web Sockets.

Guides are currently using version 2.0 of the liberty-maven-plugin. Update and verify compatibility with latest version. We can also consider implementing some automated process to update and test guides' compatibility with latest versions of Maven and Gradle plugins when they are released.

@hughesj noticed that the application project structure of the REST guide sample app is inconsistent with the Liberty Maven archetype. I'm guessing this is because the REST sample app was based on a starter project from the App Accelerator and maybe that isn't consistent with the Maven archetype?

Do we need to check the packaging structures of all the guide sample apps against the Liberty Maven archetype and update them to be consistent? (Raising here because it potentially affects all guide sample apps so far.)

As an aside, should be document that future guide sample apps should be started from the Liberty Maven archetype project?

Write an Open Liberty guide for Bean Validation 2.0.

Create a guide on how to enable Cross-Origin Resource Sharing on Open Liberty

We need feedback on these:

Overall Layout
There are two options for this one:

1. Everything in-line. Explanations followed by blocks of code, followed by more explanations, etc. This is the current format of the guides.

2. Have the code snippets, tables, output blocks, etc. flow on the right side of the page while the
explanations flow on the left side. Stripe does a very good job with this and it looks really neat: https://stripe.com/docs/api/curl#authentication

Basically, every section will be separated from every other (personally I like the suggestion by Kin in this issue: OpenLiberty/openliberty.io#92). Each section will be as long as its longest left (text) or right (code, tables, etc.) side. In other words, the left or right side will make up in length with empty space (see Stripe).

Copy/no copy
Sometimes its confusing as to what code needs to be copied to clipboard. Currently our solution is to tag snippets that don't need copying with the "no_copy" class, which prevents the user from copying the snippet when clicking it directly. Of course the users can still just select the snippets themselves. There needs to be a better distinction or all blocks should just be copyable.

Suggestions:

• Make all blocks copyable - as long as there are good descriptions, it should be clear what needs to be copied.
• Add some sort of visual aid (one sentences can be added to the "Getting started" section that says something like "blue snippets are important for building classes and must be copied, orange are not" -> can replace "blue" with an actual color block to clarity):
  • different background color for copyable vs non-copyable blocks (blueish background = copy, yellowish = no copy): https://imgur.com/a/32XCi, how it looks like on openliberty.io: https://imgur.com/a/0Y8td
  • different border color for copyable vs non-copyable blocks: https://imgur.com/a/YOQdC

Accessibility? (currently there is no way to tell either)

Website

• The section titles don't stand out enough. Look at Laraval for example: https://laravel.com/docs/5.5/authorization. There is a good amount of white space between each section header and also all h1 headers have a "#" next to them, making them stand out more. Actually, the suggestions in this issue are really nice: OpenLiberty/openliberty.io#92
• The table of contents should be static; ie. not move when scrolling through the guide (I noticed that there is already an issue opened for this: OpenLiberty/openliberty.io#90)

Summary
All in all, we need to address these quickly and update the template accordingly as this is holding us back from doing more guides atm. Also, the more guides we write and the more we hold off on these things, the more difficult it will be to change everything later. We already have 11 guides out, with 3 others finished and almost ready to go. Tweaking these alone will take a 2-3 days.

This is an issue summarizes the following issues:

• #18
• OpenLiberty/archived-guide-microprofile-intro#34
• #16

Create a guide on how you can write Dockerfiles and create Docker images for Open Liberty

So searching can work properly.

• microservices, microprofile -- Ensure that searching for microservices or microprofile will give us all the MP guides
• CDI for CDI guide -- The same for the rest of the guides and the technologies they will cover too

Do you think we could remove the mention of mvn package? Instead just say "...installation attempts to start a server. If this happens, stop the server then try again." (or something like that to help them fix the problem but without taking them into Maven concepts when they're focused on building a REST service - or other things in the other guides). Address the issue of packaging in the Maven guide. Would that work from a technical point of view?

Also, because of the relative prominence of the highlighting in this section, my tester missed that she needed to run a separate command to start the server (eg liberty:start-server) and assumed that the two commands in the grey boxes were consecutive commands to run and that one of them would do it. Then she couldn't access the app because the server hadn't started. I think we need to explicitly call out how to start the server by giving the command (in a grey box) after the mvn install step (and lose the mvn package bit, as described above).

(from usability tester feedback)

@NottyCode Please can you comment on whether you agree with this or see problems with it (before anyone implements any changes)?

NB This change would be made in the common include file so will impact on all static guides so they should all be checked against the change to make sure they all make sense still.

Guide on validating form input or data (using bean validation).

Create a guide on how to use/create MicroProfile Type-safe REST Client.

Link to repo: https://github.com/OpenLiberty/draft-iguide-bulkhead

Create a guide on how to use MicroProfile JWT Propagation.

We should add these to finish.adoc template to continue the engagement for the guides:

• share your experience on twitter/reddit
• write a blog post about your experience
• stackoverflow for questions

Suggestion from @Emily-Jiang @lauracowen

https://developer.ibm.com/wasdev/blog/2016/06/30/beta-websphere-liberty-and-tools-july-2016/

I believe this might have been discussed early on but I don't know how the discussion went.

We need a way to automatically add relevant guides (maybe based on tags?? I'm not sure what we do about tagging guides at the moment) to a short list on each guide's page.

Sometimes the suggested related guides might be pre-reqs to the current one (eg go do the REST guide to learn about JAX-RS before you try doing this MicroProfile guide) but not every reader will need to do that, while some might just be 'guides you might want to try next'.

Create a guide to demo the jsfContainer-2.2 feature to show how users can "bring their own JSF" and have it integrate with CDI.

Intro guide on MP Fault Tolerance focussing on Retry and Fallback.

Create an introductory guide on using CDI covering the essentials and in the context of developing JAX-RS services.

Write a guide for consuming REST services with AngularJS on Open Liberty.

Create guides for MP Reactive Messaging and associated APIs. Use Kafka as backend.

Securing web application using basic application security.