Environment variables reference topic

[dmuelle]

Create a new reference topic with a table for all the default environment variables.

For the table:

• down load a copy of the OL server for the ol.io downloads page
• open the following file: wlp>bin> server.bat

At the top of this file, there is a list of env variables and descriptions. Use this list to make the table.

For intro/context information, see this KC topic: https://www.ibm.com/support/knowledgecenter/SSAW57_liberty/com.ibm.websphere.wlp.nd.multiplatform.doc/ae/twlp_admin_customvars.html

But ignore the task format as it's not a task. Just use this info to write an intro to the reference table that explains the value of the information. Leave out anything pertaining to zOs

[ManasiGandhi]

@lauracowen draft link of the topic for your reference https://draft-openlibertyio.mybluemix.net/docs/20.0.0.10/default-environment-variables.html

[lauracowen]

Thanks, Manasi.

This looks fine from my point of view. The only minor comment I'd make is where it says "specific" in the intro and table title, what does that mean? If these env vars are specific to Open Liberty (implying that there are others too), it should be "Open Liberty-specific" (hyphenated). I don't know that it's necessary to say "specific" though as they are already qualified as "Open Liberty environment variables".

Could do with a link from the relevant section of https://draft-openlibertyio.mybluemix.net/docs/20.0.0.10/reference/config/server-configuration-overview.html to this new topic (the server.env section talks about the main env variables that can be set there; this new topic is expanding on that to provide the full list).

Otherwise, I'm good with this.

[ManasiGandhi]

@lauracowen I removed mentions of the word "specific" and added the link for server.env file.

[lauracowen]

Nice, thanks.

For SME, could you get someone like Chuck to take a look over it to make sure it all makes sense? If he wants any significant changes in the descriptions, can you make sure he also raises the changes against the script from which you got this info as well, pls?

Some minor comments - mostly just worth checking with Chuck rather than things for you necessarily to change:

• Not sure that user/custom should be highlighted in monospace.
• Not sure what cmd.exe refers to here (it's not an area I know much about so that's a question for Chuck to check).
• "server is run in the background via the start action" -> "server start command is run in the background." (and can you make "server start" into a link to the server start command topic?

Finally, Karen will nab you about phrases such as "will be", "via", and "install directory", btw... Just sayin' :) I know that's probably what was in the source script but I think it's fine to modify it in the doc. Ideally (talk to Chuck), give a list of such changes to someone who can update the script when you're happy with the doc.

[lauracowen]

https://draft-openlibertyio.mybluemix.net/docs/20.0.0.12/reference/default-environment-variables.html

[cbridgha]

This looks good except the description for JAVA_HOME Doesn't make sense? Sounds like you grabbed the description of the JVM options settings file. In the config overview we already use: " Indicates which JVM to use. If this is not set, the system default is used."

[ManasiGandhi]

@lauracowen I worked on your edit suggestions. Here's the link to the updated doc https://draft-openlibertyio.mybluemix.net/docs/20.0.0.12/reference/default-environment-variables.html

• Not sure that user/custom should be highlighted in monospace.

• Not sure what cmd.exe refers to here (it's not an area I know much about so that's a question for Chuck to check).

• phrases such as "will be", "via", and "install directory"

• "server is run in the background via the start action" -> "server start command is run in the background." (and can you make "server start" into a link to the server start command topic?

[lauracowen]

Great, thank you. Signing off.

[dmuelle]

Hi Manasi, the table looks good. Just a few minor comments:

• introduce the table in a separate sentence and describe what it contains, which will help with a11y/screen readers.

"You can configure Open Liberty environment variables in your server.env file to customize the Liberty environment.
The following table lists the default Open Liberty environment variables and gives a brief description for each variable: "

• I don't think you neeed a mention of ${wlp.install.dir} in the intro. It's not an environment variable and it's not discussed any further on this page. I see it has relevance on the KC page where this info came from but I don't think any of that info is in this doc.
• Spell out JVM on first mention?
• "If this is not set, the system default is used." needs a noun after "this"
• The log file directory -> the directory that contains the log file
• "user/custom configuration" avoid words with a slash (unless this is a directory path, which I dont think it is). Maybe " user or custom configuration"
• "See the README.TXT file for details about shared resource locations"- where is this file? How will the user find it?
• This directory must have both read and write permissions for the user or users that start servers-->This directory must have both read and write permissions for the user or users who start servers
• "This can be set to y to suspend the JVM on startup until a debugger attaches, or set to n to startup without waiting for a debugger to attach" Need a noun for "This". Also startup-->start up
• Last description also has "This" without a noun

[ManasiGandhi]

I worked on David's peer review for the issue. Waiting for the changes to show after the builds issue is fixed.

[dmuelle]

Hi Manasi- changes look good but this topic just needs a couple more edits

• 2nd sentence in the short description doesn't have any context. I think you should either remove it or include more info to explain why it's relevant. If you remove it, bring the third sentence up to the shortdesc.
• I think you need to tell the user where the README.TXT file is. I believe it is in _path/to/liberty_/wlp directory but you should confirm with SME
• in this sentence:
  This variable can be set to y to suspend the JVM on start up until a debugger attaches, or set to n to startup without waiting for a debugger to attach.

"startup" and "start up" are reversed. ie

This variable can be set to y to suspend the JVM on startup until a debugger attaches, or set to n to start up without waiting for a debugger to attach.

[dmuelle]

would be good to publish this topic with 21.0.0.3 if possible so we can fix and closeout related doc bug #3678

[ManasiGandhi]

@dmuelle I worked on your review https://draft-openlibertyio.mybluemix.net/docs/21.0.0.3/reference/default-environment-variables.html

• 2nd sentence in the short description doesn't have any context. I think you should either remove it or include more info to explain why it's relevant. If you remove it, bring the third sentence up to the shortdesc.

• I think you need to tell the user where the README.TXT file is. I believe it is in path/to/liberty/wlp directory but you should confirm with SME

• in this sentence:

  This variable can be set to y to suspend the JVM on start up until a debugger attaches, or set to n to startup without waiting for a debugger to attach.

[chirp1]

@ManasiGandhi @dmuelle Hi Manasi, I'm editing your topic.

• One thing that I'd like to point out so that you can work on it while I'm editing the rest of your topic is "README.TXT file in the path/to/liberty/wlp directory". I don't think that the way that the path is expressed is the best choice. Additionally, the path and README.txt could be expressed more concisely like other paths in the topic. I also think that some info from https://www.ibm.com/support/knowledgecenter/SSAW57_liberty/com.ibm.websphere.wlp.nd.multiplatform.doc/ae/twlp_admin_customvars.html could add some clarity to your topic around this path info and other path info in the topic. Would you do some research to figure out a better way to express this information?

[dmuelle]

Edited content is on vNext and will publish with 23.0.0.9. Closing as completed.