openliberty / guides-common Goto Github PK
View Code? Open in Web Editor NEWCommon Guide files
License: Other
Common Guide files
License: Other
So searching can work properly.
Create a guide for MicroProfile Healthchecks.
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.
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.
Introduction to the popular Apache logging framework Log4j, and learn how to add logs to your Open Liberty applications using Log4j
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.
Link to repo: https://github.com/OpenLiberty/draft-iguide-bulkhead
Guide on validating form input or data (using bean validation).
Write a guide for consuming REST services with AngularJS 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:
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 for processing form data in a JAX-RS service.
Guide on working with Web Sockets.
Guide for building web application with JSF.
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>
Write a guide for MicroProfile Metrics.
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
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:
Accessibility? (currently there is no way to tell either)
Website
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:
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 on how to use/create MicroProfile Type-safe REST Client.
Write an introductory guide for developing with Open Liberty Tools.
Write an Open Liberty guide for Bean Validation 2.0.
@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?
Create guides for MP Reactive Messaging and associated APIs. Use Kafka as backend.
This is to review the static MP config guide, in plan for iteration 18.4. Info to be added.
Building fault tolerant microservices with the @CIRCUITBREAKER annotation
We need to work out when to update all the sample apps/code assets to use new feature versions. Annually? Every release?
Create an introductory guide on using CDI covering the essentials and in the context of developing JAX-RS services.
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.
Create a guide that walks you through how you can consume REST services as a client on Open Liberty
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).
Create a guide that walk you through how to work with multiple modules and assemble them using Maven on Open Liberty
Create a guide on how to use MicroProfile OpenAPI.
Create a guide on how you can write Dockerfiles and create Docker images for Open Liberty
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)
Create a guide on how to use MicroProfile OpenTracing.
Using MicroProfile Config for static configuration injection
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.
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.
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).
Create a guide on how to enable Cross-Origin Resource Sharing on Open Liberty
Intro guide on MP Fault Tolerance focussing on Retry and Fallback.
Create a guide on how to use MicroProfile JWT Propagation.
Securing web application using basic application security.
Create a guide on how to use MicroProfile Config.
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.
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
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.