[Framers] [WTF ramemaker] Best Practices for HTML Online help

[Chris Despopoulos]

 So is this a SaaS product, or do you deliver a server as the product, and that server uses HTML as the GUI?
Another question... Desktop, Tablet, Phone?  All three?  If you support a finger device, then you can't use hovering to display tool tips -- you have to offer an icon to tap.
HTML GUIs make walk-throughs easier to develop.  We use bootstrap tours.  We also single-source our content, where certain tasks can get squeezed into these tours.  Our source is DITA, and we convert the task to JSON that works in the bootstrap tour.  We do our transforms on the fly (we ship raw DITA with the product), but that's just us...  You could as easily transform to JSON as part of the build.  

What about text actually drawn on the GUI itself?  Do you provide that content, or is that a specific code asset?  Labels and tooltips are often managed in a local-specific json file.  If you want rich text in the GUI you need a different way to manage that.  But once you have that, you could include links that open up the online help for more information -- that would be a good way to indicate and link to the help.  Otherwise, you need a special icon, and it has to be different than the tooltip icon.
For context links to help (or any other asset), indeed a mapping table is the way to go.  You need to own that table as a doc asset so you can freely change the targets of the given IDs.  A change should not require a rebuild of the product.  OTOH, the devs need to indicate when they add a new ID to the product so you can add it to the table and set up the link.  I'm not a fan of generated mapping IDs...  A table can get pretty big, and you had better come up with a naming convention that makes it easy to sort through all the entries.  Generated IDs probably won't suit that need.  

As I said above, we transform DITA to the online help and other formats on the fly.  We include a service in the GUI app itself to do that.  And then the online help is just another app that uses the same service.  So we own the code that makes it all happen.  That's probably out of scope for your concerns, but it's how we do things.

Hope this helps...         cud


    On Tuesday, May 14, 2019, 4:44:00 PM GMT+2, Art Campbell <art.campbell at gmail.com> wrote:  
 
 My company is developing a new browser-based software package that is specced to include screen-level context sensitive help.
The coders haven't done this before and are asking for help/assistance/advice on developing the coding standard for this and other products going forward.
I'm thinking the basics are the basics -- a call in the program goes to a mapping table that invokes the HTML help screen in a new tab/window or a popup.
What I'm looking for feedback / ideas on are a good method to call Help from the application (icon/keystroke/widget), and any Best Practices that people are already using, either on the coding or information development side.
Art

Art Campbell                                                                          art.campbell at gmail.com
  "... In my opinion, there's nothing in this world beats a '52 Vincent and a redheaded girl." -- Richard Thompson
                                                      No disclaimers apply.
                                                               DoD 358



-- 
You received this message because you are subscribed to the Google Groups "Writers & Techies on Framemaker" group.
To unsubscribe from this group and stop receiving emails from it, send an email to writers--techies-on-framemaker+unsubscribe at googlegroups.com.
To post to this group, send email to writers--techies-on-framemaker at googlegroups.com.
Visit this group at https://groups.google.com/group/writers--techies-on-framemaker.
To view this discussion on the web visit https://groups.google.com/d/msgid/writers--techies-on-framemaker/CAOW%3DE1ci8r62wUvCCvdYx2Ms6r2cadz8yks4VviDthsbXby9QA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.