MadCap Software Forums

Hi, all. I'm just getting back into documentation after a few years in a QA role, and would appreciate some feedback on the best way to approach a particular design for a help page.

The application we make has a number of screens that support multiple related workflow steps. For example, one screen is used for creating and querying tables and graphs (which we collectively call "objects"): in this page, the user can select an existing object to view it, or move it into a folder, or delete it, or rename it, etc. They can also launch a wizard to create a new object. Basically, anything you can do with an individual object can be initiated from this screen.

This makes it a bit of a challenge when it comes to context sensitive help. Because there are a number of possible actions, all of which are perfectly valid, I can't jump directly into topics about any one workflow, at least not without the risk that users who need help with a different workflow will get frustrated. So instead, I'm planning to make what I call Landing Pages. These pages will provide a high level overview of what the application screen is for, along with links to topics about each of the workflows and tools that can be accessed from the screen.

What I'm after is a help page that's divided into four panels. The top half of the page will contain the overview information. The bottom half will be sub-divided into 3 columns. The left most column would contain links to process help (i.e. step by step on how to complete a given workflow), the middle column would contain links to tool help (i.e. detailed info on what each button does), and the right side column would contain links to more conceptual or educational topics (i.e. best practices, examples, troubleshooting, etc.)

Now, finally, here is my question: my plan is to try to use Divs to layout the panels. But where should I apply the Divs? Would it be better to create a master page containing the Divs, and only put the content in each topic? As I recall, with a master page you set aside a body proxy for the topic content, so I'm not sure if what I'm after would really work as part of a master page.

Or should I just add the Div structure to each topic individually?

Thoughts?

What type of outputs will you be building? Just online? Online and print? If print, PDF or Word or FM or combination? If you have to do online and print, then I think you want to go with a three column table instead of DIVs, because the print outputs either don't deal well with DIVs at all (Word) or are ok with DIVs but not so much with floating or positioning (PDF), which is what you'd have to do to get the column effect.

The first thing that jumped to mind was relationship tables, but I don't think you get that much control over the positioning of each element in the associated proxy. I haven't used relationship tables or the proxy, so I don't know how flexible they are. If they're not flexible enough to give you that amount of positioning control, then I'd suggest a snippet with a three-column table formatted as you want with placeholder text, then after inserting the snippet to the topic, convert the snippet to text and add the appropriate links/xrefs to each column.

Hopefully someone else has a better solution.

KevinDAmery wrote:Now, finally, here is my question: my plan is to try to use Divs to layout the panels. But where should I apply the Divs? Would it be better to create a master page containing the Divs, and only put the content in each topic? As I recall, with a master page you set aside a body proxy for the topic content, so I'm not sure if what I'm after would really work as part of a master page.

Or should I just add the Div structure to each topic individually?

Thoughts?

As LTinker has already mentioned, using DIVs may be problematic for some outputs, so it's best to test out some layouts first to see what works best.

Whether you put the links in your topics or on a master page will depend on how you want to create the links. If you're putting them on a master page, then the links aren't editable at the topic level and you must be able to generate all the links using proxies; such as a relationship proxy or miniTOC proxy. If you need to edit the links manually at the topic level, then they'd have to be in the topic body.

Given that you have well-defined types of topic, I'd definitely suggest having a look at relationship tables; then you could use a relationships proxy (in a master page) which would generate all the links for you. However, I'm not sure the proxy can be split into 3 columns, and would probably have to be in one block. However, you can break that up with headings for each relationship category, so you could have a heading for each type of topic (using MadCap|relationshipsHeading classes).

How's the masterpage supposed to know what goes into what div? Means: If you need to enter changing content into divs you need the divs in the actual topic ...
But you can produce templates that contain those divs already. Maybe you should use a stylesheet trick to make it easier for the editor to find the right div.

Using the fact that the "default" medium is the standard medium for the XML editor:
1. Generate a medium called "screen" in the stylesheet.
2. Generate a class each for each sort of div (if you haven't done so already).
3. In the "default" medium change the background-color of the 5 div classes to 5 different colors to mark the purpose. (or add a border with different colors or change the coolor of the font, or ... )
4. In the "screen" medium change it back to white (or whatever it's supposed to look like in the output)

OR:
In the templates there are paragraphs with a special class used as headers in the divs - they tell the editor which div it is. In the stylesheet that class is set to "display: none;".That way those paragraphs don't make it into the output.

Thanks, all.

The output for the moment will be CHM. We may eventually produce Word as well for print purposes, but since these are hyperlinks I don't expect them to work on paper As such, I would probably use a different approach in the print output through conditional formatting. Three lists one after the other is less problematic in print than in on-screen help, since scrolling isn't really a problem for print output.

I'll take a look at relationship tables. If that doesn't work, I may just do things the old fashioned way and build the div structure on a topic by topic basis. This type of topic only affects context sensitive linking to the "main" screens of the application, which means there are a finite number of them to worry about.