Runnable JAR topic is mostly redundant and much of the later sections don't make sense in context - needs tech review and update

[lauracowen]

https://openliberty.io/docs/ref/command/#runnablejarfiles.html

Also, there is a dead internal link ('Environment variables').

The Exit Codes and Server Process sections aren't relevant.

cc @NottyCode

[bsbyrd1]

@cbridgha Could you give the Runnable JAR topic a review:
https://openliberty.io/docs/ref/command/#runnablejarfiles.html

@chirp1 To your idea Karen, we might just remove the The Exit Codes and Server Process sections, create a new topic for this content, and link to that new topic from the server command topics.

[cbridgha]

Completely agree on the later sections being removed and relocated to standalone doc (Exit codes and server process).

The rest is ok, I see the relevant info on how to debug, two phase commit etc is buried in the Env Variable descriptions. Just need to make sure those concepts are easy to spot.

Also - Maybe refer to the runnable jar packaging in the beginning (possible hyperlinking that section again)

[NottyCode]

I don't think this should be in commands doc. This is not a command. I think it should be moved to general reference and the package command should link to it for background on --include=runnable

We do not need to tell people how to run a runnable jar. I don't think we need to tell people where it is written on both windows and linux. I think we can tell them it is in their user home and tell them where below. I think most people will be able to resolve that.

If we cross link we should hyperlink the cross link:

 environment variable (see [Environment variables]).

this is not correct:

If you stop the active shell in any other way, the extraction directory is not cleaned up automatically, you must clean it up manually.

since you can do kill and it'll tidy up just as long as you don't do -9

[Charlotte-Holt]

@lauracowen @NottyCode I've made some updates to the Runnable JAR files topic and merged it to draft for review. A few things:

• I still need to move this to general reference, as Alasdair suggested, and it'll need to get included in the TOC. The package server command already links to this topic in the "See also" section, so I think we're good to go there.

• Do we want to link this to the Server configuration overview topic (https://openliberty.io/docs/ref/config/serverConfiguration.html) - either a link in the "See also" section or something along the lines of, "For information on specifying (or accessing?) environment variables, see..." above the env variables table?

• In the sentence, "By default, files are extracted to the wlpExtract/<jar file name>_nnnnnnnnn in the user home directory", should I remove "the" before wlpExtract/<jar file name>_nnnnnnnnn or add a noun after wlpExtract/<jar file name>_nnnnnnnnn? It sounds off to me as it is now, but that could just be me.

Let me know your thoughts!!

[lauracowen]

Thanks for doing this.
Answers to your questions:

• Okay.
• Ah yes. Maybe the "For information..." sentence above the Environment Variables table. It would make it look more 'introduced' too.
• Yes, good point, I agree. I think removing the 'the' would work.

Some other comments:

• I think you can remove the whole of the paragraph that starts "To stop the Liberty server...".
  • CTRL+C is obvious so it's not necessary to document.
  • I think the fact that it's previously described as a temporary extraction directory means it'll get cleaned up. And people are used to things not being cleaned up if they force quit something (which is how I interpret the last sentence of the paragraph).
• I don't think the 'Usage' header is appropriate as it is for command topics - just remove the header. And can then collapse the two paragraphs that follow it into a single one as they're both about extraction locations. It's all just part of the intro then.

Otherwise, looks good, thanks.

[Charlotte-Holt]

@lauracowen I made the updates you suggested and merged them into draft. Let me know if further updates on this topic are necessary. Thanks for your help!

[lauracowen]

Thanks. Can you move the file out of the .../ref/commands/server directory and into the ...ref/general directory? (you'll need to update the relative link to the serverconfiguration file). I think moving the file will automatically get it added to the toc under the General card.

[Charlotte-Holt]

@lauracowen Done! Updates in draft.

[Charlotte-Holt]

Complete! Closing this issue. https://openliberty.io/docs/ref/general/#runnablejarfiles.html