In JavaFX, Is there a best practice or framework for creating program help files? [closed] - javafx

Question

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed last year.
Improve this question
I've been experimenting with using HTML as a structure for generating a help information area for a desktop program that I've finished writing and that seems to work ok, though I don't really like the way it is turning out and I began to wonder if perhaps there might be a better way to go about it. Perhaps a library that makes generating and linking content within Java a little easier in that context or some other means that I'm not aware of.
I did some Googling on the topic but found nothing specifically in reference to help menu / content creation.
Does anyone know of any libraries out there that would make it easier to create help info for end users?
Or, is there a "best practice" for doing this or any other method to that end?
Thank you,
Mike

Answer 1

What does Idea do?
Intellij is large java app that has decent help documentation. You could look and see how they did that, if that is something you wish to emulate. I think it is mostly good quality writing and organization rather than tool support, though I guess they use decent tooling too.
I did a quick check to see how idea create their doc. They write in markdown format. Here is the markdown style guide they use for creating the document, in generated html form and in markdown authoring form. A repository of docs used for one of their products is their open source sdk docs. The SDK docs project is an Idea project, so I guess they just use Idea for authoring. If it seems to be something that would help you, you could try cloning the project and generating documentation from it or contacting the project contributors for more info.
As far as tying the help content into your app, either you can display it in situ using a WebView or link to it externally using HostServices. You could study the help system used within Idea to see how they generally do that, e.g. help menus used, key commands responded to, icons used to link to the help system, etc.
Generally, the way it works is:
The document is written in markdown then processed and rendered to html.
The html documents have copious anchors throughout.
The help menu items link to the anchors directly.
Help menus and shortcut keys follow platform specific conventions and differ between Windows and Mac.
There is a single ? icon in dialogs which appears in a consistent place and it links to an anchor in the html for context sensitive help in the dialog.
The documentation itself is hosted on a website so it can be accessed independently of the application.
The app launches an external browser to view the help rather than using something like a WebView to show the help internally.
Additionally, Idea will use tooltips which show up on hover. Tooltips aren't used for every control or UI element, only certain ones. If there is a keyboard accelerator which can be used to trigger the control action, then there is a tooltip for it, and in the tooltip it lets you know what the keyboard shortcut to trigger it is.
The rendered HTML to which the app is linked is hosted at the jetbrains website.
Linking to HTML help
You could:
Link to your own hosted website, OR
Link to html files packaged with your app.
Both could be rendered by either WebView or a browser showing a document using HostServices, using the file: protocol to access html files packaged with your app or https: protocol for files hosted on your web server.
What does SceneBuilder do?
For a pure JavaFX application, SceneBuilder is quite large and complex. It has no reliance on internal help at all, just a single help menu item, accessible via an F1 shortcut. The help links to a website authored and hosted by Oracle (using the standard tool Oracle use for authoring most Java platform docs, which is likely a commercial tool). It is not as nicely integrated and context sensitive as the Idea example but it does demonstrate a simple approach to documenting an app via an external website.