openliberty / archived-guide-log4j Goto Github PK

We ran a build with some updated dependencies and with java versions 9/10, the build failed: https://travis-ci.org/OpenLiberty/draft-guide-log4j/builds/391965448?utm_source=github_status&utm_medium=notification

@evelinec @Ahmad-Ayyoub

Consider alternative like JSON-B or whatever is appropriate.

There is a known security vulnerability with com.fasterxml.jackson.core:jackson-databind >= 2.9.0, < 2.9.5.

Current README.adoc defines the project id to microprofile-metrics
:projectid: microprofile-metrics

It causes the metric guide link to this guide.

i.e. https://qa-guides.mybluemix.net/guides/microprofile-metrics.html points to the log4j guide instead of the metrics guide.

Please correct the projectid.

Overall

• Try to omit repetitive or extraneous words/sentences. Also break up long paragraphs into smaller paragraphs or bullet points.

• Only capitalize the first word in a title and any proper nouns that follow. For example, in a title such as "Starting the Liberty application," you don't need to capitalize "application," but you capitalize "Liberty" because it's a name/proper noun.

• Use the code phrase format to indicate file names, directories, method names, class names, etc.

• When you have something that shouldn't be translated and is formatted as a code phrase, add a word that is translatable after the code phrase, for example, "the org.apache.logging.log4j package." Words like "package" should go after the code phrase.

• As much as possible, avoid using first person ("I" and "we").

• Also, if you want to state that something is "popular" or "recommended," mention why that thing is better or advantageous instead. To use a basic example, I can tell you, "This product is good." That statement is not as convincing as, "This product has x amount of memory and runs at x speed." or "You can use this product for x, y, and z."

"What you will Learn" should be "What you'll learn"

• Avoid using subjective/relative words like "popular" or "new." If the reader views the guide much later, words like these might not be applicable anymore.

• Try to tighten the first paragraph. For example, it mentions "add" twice. Focus on what the user can do. I don't think we need to mention the introduction of Log4j.

Why use Log4j

• Shorten "Why use Log4j when there is Java Logging API" to "Why use Log4j". We try to avoid using "there is" or "there are."

• Also, break this paragraph into at least two smaller paragraphs and see if you can omit anything. I'd say make one paragraph on the Java logging API and another paragraph on Log4j.

Getting started

• Remove "To do this". The "Creating a RESTful web service" guide simply states, "...clone the Git repository and use the projects that are provided inside:"

Adding Log4j loggers to a Liberty application

• The first sentence, "The following instruction describes the typical steps involved in using Log4j loggers in a Liberty Application." basically repeats the title. You can omit this sentence and jump right into giving the instructions.

• Instead of using <> to highlight the word "dependencies," use the code phrase format instead. Also use the code phrase format to highlight words such as pom.xml.

• Omit the sentence, "For the most part, that’s all there needs to be done code wise to start developing an application using Log4j as the framework." I think it's already implied because the user can see that they have reached the end of the section. :)

• Address your user directly and omit (as much as possible) words such as "people," "users," and "developers" when referring to your audience. For example, replace "For the people who are serious about their application logs, like writing log to a database instead of files," with something like, "If you want to write logs to a database..."

• Sentences like "The next step in the configuration is to set up the Log4j configuration file." are implied and can be removed.

• Missing project information section before publishing, for example:

:projectid: microprofile-rest-client
:page-layout: guide
:page-duration: 20 minutes
:page-releasedate: 2018-04-20
:page-description: Learn how to use MicroProfile Rest Client to invoke RESTful services over HTTP in a type-safe way
:page-tags: ['REST', 'MicroProfile', 'Rest Client', 'microservices']
:page-permalink: /guides/{projectid}
:page-related-guides: ['rest-intro', 'cdi-intro', 'microprofile-config']
:common-includes: https://raw.githubusercontent.com/OpenLiberty/guides-common/master
:source-highlighter: prettify

• Please use back quote marks when you refer to a specific term/variable/messages in the code or file names so that these terms can be emphasized.
  For example, Error 404: javax.servlet.UnavailableException: SRVE0203E: Servlet [application.servlet.LibertyServlet]: application.servlet.LibertyServlet .
  log4j2.xml, server.xml ...

• Please use the code injection style when you refer to a code snippet in the README.adoc
  For example,

[source, java, indent=0]
----
include::finish/src/main/java/io/openliberty/guides/inventory/client/SystemClient.java[tags=client]
----

• When you refer to a specific code snippet, show the reader the full class path where the code is located.
  For example,
  ".... Create the SystemClient class in the src/main/java/io/openliberty/guides/inventory/client/SystemClient.java file ......"

• Show the entire server.xml file, not portion of it.

• Why do you have README.md in both start and finish folder? all instructions should be in the README.adoc (which is the guide)

• Where is the HelloServlets class? Please be more clear when you write instructions. Imaging the reader is someone knows nothing about this application.
  Use the style such as " Create the ... class in the ... file (full path) and add the following code snippet: ..."

• Missing "Try what you'will learn" section and "Building and running the application" section

:projectid: microprofile-metrics needs to be changed to something related to log4j. Right now, there is a collision in URLs for this guide and microprofile-metrics guide

Initial commit of log4j sample code to draft-guide-log4j repo