Online Help structure for modular products

This forum is for all Flare issues related to the HTML5, WebHelp, WebHelp Plus, and Adobe Air Targets
Post Reply
IUseItAsACrash
Propeller Head
Posts: 22
Joined: Wed Jan 30, 2019 2:37 am

Online Help structure for modular products

Post by IUseItAsACrash »

Hello Flare users

I am currently developing a new help system for our company. Up to this point, only a few PDF manuals have been created by my predecessor, and as the first official Technical Writer I got to choose a new tool (obviously opted for Flare) and start from scratch.

Our product is made of four modules (we call them modules) for which licenses can be bought individually. A combination of each of the modules is possible, as well as a Suite which contains all licenses. I am currently trying to figure out how to structure the online help system in order to make the help content for the specific module available to users of the respective licenses. As far as I can see it, the following options exist:

- One online help which contains all the content for all modules, irrespective of the license (the easiest way, but not acceptable)
- Individual help systems for each module, accessible via a global start page

Are there other options I am not seeing?

Any help is appreciated.

Thank you!
ajturnersurrey
Sr. Propeller Head
Posts: 346
Joined: Fri Nov 05, 2010 3:30 am

Re: Online Help structure for modular products

Post by ajturnersurrey »

It rather depends how many modules there are and how intertwined they are...

If you have modules A, B and C but people most often buy A and B together or they buy C alone you might want to have help for 'A and B combined' as well as help for 'just A' or 'just B' or 'just C'. This involves setting up help for individual modules, but also building targets for some combinations like A and B too. This would be more helpful to customers, with a small amount of extra work for you.
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: Online Help structure for modular products

Post by NorthEast »

Is there a reason why one help output is not acceptable?
You could produce a separate help output for each combination, but it gets more unwieldy as the number of modules increases.

I document a product with optional modules, and we just produce one single help system.
We just assume people know what they've got (and haven't), and also from a sales perspective we think it's good to show what other modules you can add.

It depends how your modules behave with each other though - e.g. whether using module A standalone is significantly different to using module A and module B together.
In my project, it's easy enough to document any differences in-place. We also use a search filter to help find topics on a module/subject, to help filter out content that's not applicable.
IUseItAsACrash
Propeller Head
Posts: 22
Joined: Wed Jan 30, 2019 2:37 am

Re: Online Help structure for modular products

Post by IUseItAsACrash »

Thank you for your answers!

The modules are not intertwined at all. The product is an email gateway, the four modules cover different functionalities: spam protection, encryption, email disclaimer management and sending of large files.

Having only one output would definitely be the easiest, but this approach was rejected by my superior last week. I will discuss this again at the next meeting.
ChoccieMuffin
Senior Propellus Maximus
Posts: 2630
Joined: Wed Apr 14, 2010 8:01 am
Location: Surrey, UK

Re: Online Help structure for modular products

Post by ChoccieMuffin »

Would four separate helps not do the trick?
Started as a newbie with Flare 6.1, now using Flare 2023.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
IUseItAsACrash
Propeller Head
Posts: 22
Joined: Wed Jan 30, 2019 2:37 am

Re: Online Help structure for modular products

Post by IUseItAsACrash »

Four help systems would be possible, but there are also customers that combine two or three modules.

Also, there are situations in which certain dialog boxes display different content depending on the licenses of the user. For example, options for encrypting emails may be added to a message tracking dialog box.
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Online Help structure for modular products

Post by Psider »

In a previous job we had a modular product and clients could have almost any combination of modules and version of each module.

We had one project per module, with a parent project to handle the merge; not global project linking, just the ToC merge. We didn't use global project linking, possibly because it didn't exist at the time, but also partly for legacy reasons converting from chm files to a webhelp.

Because we didn't know what combinations of products clients might have, our devs created a custom solution.

Rather than publishing to the standard merge structure, we published to individual standalone folders by module and version number:
ModA
1.0
1.1
2.0
ModB
1.0
2.0
ModC
1.0
2.0
3.0

Now I'm simplifying because I don't know the technical detail, but this is what it did in my understanding.

Each installed module would pass an id to a small tool, which would then "fake" the directory structure to make the help work. So while the help lived in directories as above, the application for client A would "see":
AppHelp
- ModA2.0
- ModB1.0

And the application for client B would "see":
AppHelp
- ModA 1.1
- ModB 1.0
- ModC 2.0
Vibeke B
Propeller Head
Posts: 73
Joined: Thu Mar 15, 2018 7:14 am
Location: Denmark

Re: Online Help structure for modular products

Post by Vibeke B »

I have looked at this again and again and I cannot get my head around it.

As far as I can see, the system described above is not for a context-sensitive help, rather for an online knowledge base like help. Is this correct, or have I misunderstood something? I cannot see how this is using multiple targets, or am I too narrow-minded in how I am looking at it?
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Online Help structure for modular products

Post by Psider »

Vibeke B wrote: Thu Aug 17, 2023 5:19 am I have looked at this again and again and I cannot get my head around it.

As far as I can see, the system described above is not for a context-sensitive help, rather for an online knowledge base like help. Is this correct, or have I misunderstood something? I cannot see how this is using multiple targets, or am I too narrow-minded in how I am looking at it?
Is this in response to my post? If so, it was a context sensitve online help system using the merged help feature for multiple Flare projects.
Post Reply