Providing user help documentation -- what is the standard in 2024?

[QuinnMartin]

In the old days of Windows you would press F1 in any application and get useful help documentation.  For whatever reason, this functionality was scrapped around 2005-2010.  I've never understood why this is, as the old context-sensitive help was implemented in the vast majority of programs and was something I used all the time.  I thought it was a great design feature in Windows.  But nowadays, F1 doesn't seem to do anything in most apps or I get broken functionality so I don't even bother hitting the F1 key and just Google for help.  But that's just me, I know.

So my question is: What is the *preferred* standard for user help in 2024 by users of small to medium size Windows/Linux applications.  What do users expect?  I would prefer to design around that.

Lately for one of my apps I have just been providing a PDF user manual.  I don't feel this is a great system because a PDF is not context-sensitive at all, it's basically a big ebook.  Not too many people will pick up a PDF and begin studying it, much less go through it to solve a minor problem.  But personally I find it very easy to edit, I just fire up InDesign and start editing, and it's super easy to generate the PDF.

I thought about implementing my own simple F1 help system.  Commercial solutions like Help+Manual are way too pricey for small time developers and I don't know if there are any viable alternatives.  I'm sure a very simple help system based around a TRichEdit would work fine.  But if no one uses F1 much these days I can stick with PDF.

I guess another option is to put context-sensitive help on the website and have F1 trigger a browser call to bring up the desired page.  To me it's kind of hamfisted as it switches focus away from the app and opens the browser, but from a business standpoint I can appreciate that it creates some constant, continuing interaction with the website.  Is this a generally accepted method?

Thoughts?

[JanRoza]

I mostly create my help in html files, so pressing F1 or the help button in my programs will show the help info via the browser. Works fine in Windows and Linux.

[MarkMLl]

I mostly create my help in html files, so pressing F1 or the help button in my programs will show the help info via the browser. Works fine in Windows and Linux.

The problem there is that unless you embed your own browser, you will hit problems if the browser chosen by the app clashes in some way with the user's expectations.

For example, if the user already has Firefox running an attempt to start a second copy will fail, particularly if it is set to always start via a a dialog(ue) asking what profile should be selected.

You're less likely to see that if you instead use e.g. PDF, but OTOH it's nowhere near as good as HTML at jumping to a specific section of a page.

MarkMLl

[Thaddy]

I use fpdoc to write both the user documentation and the technical documentation.
Once setup to your liking it is very easy to use.
You have the benefit of choosing different formats, including pdf and html.

[JanRoza]

@MarkMLI

For example, if the user already has Firefox running an attempt to start a second copy will fail

On my Linux Mint pc the help info just opens a new tab in Firefox, so no problem on this side that I'm aware of.

[QuinnMartin]

Just for showing basic HTML and CSS on a website, is there a good easy-to-use mini-browser for Lazarus that can show basic HTML and CSS on a website?  I'm not sure if there's one built into Lazarus or if any are available via the online packages.  Of course I don't want to expose users to injection exploits, security vulnerabilities, and other problems if they start navigating to other websites.

Perhaps it is better to leave that kind of heavy lifting to the default browser?

[Thaddy]

HtmlViewer from OPM is lightweight and supports css. Does not depend on browser code and has been around for decades.

[QuinnMartin]

HtmlViewer from OPM is lightweight and supports css. Does not depend on browser code and has been around for decades.

Thanks Thaddy, I will check it out. 

[MarkMLl]

On my Linux Mint pc the help info just opens a new tab in Firefox, so no problem on this side that I'm aware of.

Won't work if always set to prompt for profile selection.

Broadly speaking, I'd suggest keeping this sort of thing in-program if possible so I agree with Thaddy's point about getting s simple HTML viewer... and then being careful that your HTML editor doesn't rely on Javascript and excessive CSS.

MarkMLl

[QuinnMartin]

Yeah I used HtmlViewer and fphttpclient to load an HTML page that had light formatting and CSS, with a single image.  First off it wouldn't load the images at all unless the image URLs were converted to base 64 and formatted as a data URI.  Once I got that sorted out, it was taking 65-67 seconds to load a 2 KB page!

Not sure what the bottleneck is with that but I will work on making the CSS and HTML as light as possible with the bare minimum of formatting.  If performance is unacceptable I'll fall back on just having local RTFs loaded into a TRichMemo.

[QuinnMartin]

I just wanted to update this thread but I think I've hit upon an awesome solution: Sphinx for Python.  You write your documentation in simple text with markup, and Sphinx uses that to generate multiple formats like HTML help (with a choice of themes), PDF, JSON, and so on.  So you're no longer tied to one specific type of help format.

I found that Lazarus's THtmlViewer will definitely handle the simpler HTML+CSS formats produced by Sphinx, but it chokes on the more complicated third-party themes like Bootstrap.  Thankfully it's a one-line edit in Sphinx to change the theme.