We are creating a web tool and one of the functionalities are not very clear for a small percentage of the users. So far, we have implemented very simple one-sentence long on-hover tooltips. Yet, a small percentage of users are still scared* to work with it or simply do not understand it.

* it might disrupt their companies work flow. Our customers are small companies with potential no IT department.

What is the best way to implement a detailed help article?

Option A:

A modal overlayed on the application like the 'edit modal that is being used everywhere. This would be a scrollable modal that explains the functionality of this page or component. You have to be logged in to see this.

Like this fast mock up (blurred some irrelevant data): enter image description here

Option B:

A separate page that might redirect to help.dummyCompany.com/lang/my_page/my_component or something similar. This would include the same data as Option A but on a separate browser tab. However, everyone can see this since there is no login required.

Like this example of hotjar: enter image description here

  • 1
    Often, the first one is done badly and contains only obvious information, so one ends up clicking "read more" and doing the second one anyway... Commented Sep 1, 2022 at 11:46
  • @LukeSawczak We do think of having identical information on both versions anyway. This should be the very last resort. We got a very simplified design, tooltips & small description. We are thinking of having a written out explanation & youtube video as demo.
    – Wojtek322
    Commented Sep 2, 2022 at 14:19

2 Answers 2


It always is tempting to RTFM the user when they don't understand your design, but it's unlikely to help your cause. An app I've worked on had little blue (?) icons everywhere which would summon a manual page relevant to this item, but the majority of users never even registered it being there and only a tiny portion ever used it.

The root cause here likely is wording. If users don't immediately understand what a button will do, they are indeed afraid of clicking it. For example, a button titled ⬆ Amplify is generic and somewhat unclear as to what it does, while 🔊 Increase Volume is much better.

Another example would be to be explicit about which buttons do and don't cause immediate changes; IPv4/6 could be a toggle between the two and break everything, while View IPv4/6 settings can have the user confidently click the button without having to fear for the worst. And once they click a button, you're free to plop them into dialog windows and such where you have much more space to explain stuff to them.

But to strictly answer the question

Should help articles be part of the program itself or be available online?

Unless you have good reason to hide the help center, it should be available online and SEO'd well if possible. And having a help center embed inside the app won't hurt. Maintaining two different versions of help resources or blocking the release of the software until the help section is done is generally unwise though.

  1. Users don't RTFM.

  2. Users don't RTFM.

  3. Users don't RTFM.

  4. (Some) Users would like to RTFM but don't get the time to do so from their boss(es).

  5. If that fits to your web tool:

    I really love Jenkins' inline help with a Jenkins' inline help icon next to (almost) every control/widget which toggles help right below it:

    No inline help open. But note the dynamic quickhelp below Schedule
    derived from the field's current content!
    No inline help but quickhelp nevertheless
    If Schedule is empty although 🗹 Build periodally is selected
    Schedule empty
    Inline help for Build periodically and Schedule after selecting their Jenkins' inline help icon
    With inline helps

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.