This 2-hour tutorial explains the basic principles of progressive disclosure and includes a shoot-out between two tools that offer various levels of support for implementing progressive disclosure in web-based help systems: Adobe RoboHelp and MadCap Flare.

1. Progressive Disclosure
Putting the User in Control
Jang F.M. Graat
UA7
1
© 2013 JANG Communication, Amsterdam, Netherlands. This presentation is created for a
tutorial first delivered at the tcworld 2013 conference in Wiesbaden, Germany. Photo
material is either purchased from one of the available photo stock websites or taken from
internet pages that did not indicate any copyright notices.

2. Who’s Talking ?
• Jang F.M. Graat
• Tech Comms
• Structured Frame
• DITA, XSLT, JS, CSS
• RoboHelp, MadCap
• Minimalist
• Philosopher
2
After studying Physics, Psychology and Philosophy it was time for me to get a paid job. Lady
Luck put me on a fast track into the high-tech computer industry, where I embarked on a
career in technical communication that took me around the globe many times. I have taught
myself all I need to know and I specialize in teaching techie stuff to not-so-techie audiences.

3. Progressive Disclosure
Some Everyday Examples
3
Progressive disclosure is not very new, but in the technical communication domain it is not
widely used yet. But we all know the principles, which may become clear by looking at some
everyday examples we will all know, but might not recognize as being progressive disclosure
techniques.

4. Getting Started
4
The first example is literally when we get started in our daily jobs. Well, most of us get
started this way (some keep running all night long).

5. 5
I like to keep my desktop pretty clean. No shortcuts to dozens of programs or files, as I do
not need most of them all the time. My desktop expresses my tendency to minimalism: only
show me the info I need right now. After Windows has started, this is what I see. A minimal
set of options to choose from. To start an application in Windows, I click on the Start button.

6. 6
The Start menu shows me the most used applications in a short list. Next to the list are some
other areas that I might want to explore, but let’s stick with the applications for the moment.
I can start any of these by clicking on the application name.

7. 7
If I want to open an application that is not in the most-used list, there is always the option
view the full list of applications via the All Programs entry at the bottom.

8. 8
But even this list may become very long and to prevent a lot of scrolling and searching, many
applications are organized in separate folders.

9. 9
Clicking on one of the folders reveals its content. There may be nested folders, so the
process continues until I have found what I am looking for.

10. 10
If I did not find what I was looking for, or changed my mind, I can still return to the previous
view via the “Back” option at the bottom. This might seem trivial but is an important aspect of
progressive disclosure: you should always offer the user a way back.

11. 11
One more detail of progressive disclosure in the Windows Start menu is the feature that
keeps a list of recently opened files. If the application has such a list, the Start menu includes
it and offers a direct way into the list by hovering over the arrow to the right.

12. 12
From here, I can open a document in the application with one click. The whole process shows
how the options that are shown are controlled by me, the user. At every click, another part of
the available options are revealed.

13. Booking a Train Ticket
13
We can see good examples of progressive disclosure on the web, too. The website I will show
you offers train tickets via the internet. The design had to enable people to interact with the
selling software in more or less the same way that they would when purchasing a ticket from
a counter with a human being to interpret what they want.

14. 14
After entering my point of departure, destination and travel dates, the Deutsche Bahn website
shows me a list of available train connections. It immediately includes pricing information
when available, plus number of transfers and total travel time. For most purposes, this
information is sufficient to make a decision and move toward booking the train ticket.

15. 15
If I want to see the route and how much transfer time I have between trains, I can click on the
arrow in front of the indicated train schedule. This opens a section on the page that was
previously hidden. Here I have details about each of the trains available. The information that
was already visible is not replaced, and there is always the option to hide the extra info again.

16. Embedded Assistance
16
Progressive disclosure gets more interesting in areas where the user might not completely
know what they are looking for. Early attempts to create so-called Wizards were not always
succesful (who ever found Clippy or the cute but stupid little dog in MS Office useful ?). There
are some examples where integration between the software, documentation of that software
and user assistance have been implemented in just the right way.

17. 17
This is my MacBook Air desktop. The menu bar shows symbols for basic services, such as the
WiFi connection. The symbol itself shows whether I have a connection and how strong the
signal is. If there is a problem with the internet, there will be an exclamation mark on the
symbol.

18. 18
If I want to do something about the WiFi connection, I can open the menu via the same
symbol. Apart from joining another network or switching my WiFi off, I can also open the
Network Preferences page in the System Preferences.

19. 19
On the Network Preferences page, I can see all network connections with their status, plus a
limited amount of information that I might be looking for. There are some general options
that I can switch on or off here, and for an option that might not be immediately clear there is
a short text to explain what the option will achieve. If I am looking for technical details about
the connection, I can click on the Advanced button near the bottom.

20. 20
This pulls down a panel with multiple pages, each of which has a lot of technical information
available. The pages allow making changes and do not offer a lot of extra explanations, as
people handling these settings should know what they are doing. Making the pages look
more technical does keep newbies from making any changes here. Clicking Cancel or OK
makes the panel move up again and returns to the Network Preferences screen.

21. 21
For the non-techies, a wizard or assistant is included. Clicking the button Assist me brings
up a question which type of assistant the user needs, as there may be various reasons why
the Network Preferences were opened in the first place. Note that if there is a problem with
the connection, clicking the failed network icon allows jumping straight into the Diagnostics
wizard.

22. 22
If I choose to set up a new network, the assistant shows me basic information and asks me to
supply a name. The buttons Go Back and Continue are always available. I always have a way
to return to the previous step, which is very important in progressive disclosure.

23. 23
The dialog that opens via the More Info button shows a short description of the parameter
that is required in this step of the process. The window of the Network Setup Assistant is not
hidden or changed: the panel slides down out of the window’s title bar and slides up again
when clicking OK. Nothing in this process should scare the newbie users or give them the
impression that they have done something that cannot be undone.

24. 24
Steps that involve a choice between various options are shown in a language that does not
contain too many techie words, or explains those words where needed. Each step in the
Network Setup Assistant covers one single choice or one single entry. And there is always a
button to show More Info. This is progressive disclosure at its best.

25. Minimalism
Main Principles
25
The paradigm that lies at the basis of progressive disclosure is minimalism. Without redoing
my presentation about minimalism at past tcworld events, I will briefly indicate the main
principles of minimalism. Those principles should be kept in the back of your mind always,
even when you are not working on progressive disclosure.

26. Action-Oriented
26
First principle: your user assistance should focus on doing things. Users are not browsing
your help system because they enjoy doing it and have nothing better to do. Users who call
up the user assistance have a problem that they need to solve, and normally they are in a
hurry. Don’t explain how a feature works if the user does not need to have that knowledge to
succesfully use the feature. I don’t know how a combustion engine works but I can still drive
a car.

27. Support Error Recovery
27
A user may not know that they have made an error until it is too late. You should include
enough information so that the user can confirm there was no error (e.g. showing a step
result) and indicate what to do when they have discovered something is wrong. A basic
technique in Progressive Disclosure that rests on this principle is always providing a way to
go back to the previous step.

28. Reading-to-do
28
This ties in with the first principle: users do not open the user assistance to kill the time, they
read the instructions to solve a problem and get ahead with their work. An assistant that
takes the user out of their own documents or tasks and merely wants to educate the user
based on an abstract example is useless to most users. Wherever you can, allow the user to
perform steps and return to your assistant for more information after doing so.

29. Dynamic HTML
HTML, CSS, DOM, JavaScript
29
Good Progressive Disclosure takes a lot of work to implement, and you probably need to do it
in close cooperation with the software developers of the application you are documenting. In
this tutorial, we are going to look at the basic techniques you can use without depending on
the developers’ time and cooperation. The technical components for this level of progressive
disclosure are HTML, CSS, DOM and JavaScript. Let’s look at each of them and then at what
the combination of these techniques can achieve.

30. HTML
30
The first technology that is required is HTML, HyperText Markup Language. Defined in the
early days of internet, when there was no World-Wide Web yet. HTML allowed the WWW to
come into existence, as it established a standard platform to display information and to
create hyperlinks that take you from one document to another (wherever that may be). The
above picture is NOT the inventor of the world-wide-web, Mr Tim Berners-Lee.

31. 31
HTML should be familiar to everyone in this audience. Basically, each element is wrapped in
tags that determine the formatting in a browser. The above example is what we will be using
throughout most of this tutorial. It shows a task with a number of steps and substeps.

32. 32
This is what the HTML looks like in my Firefox browser. Nothing special, but then we have not
added any fancy stuff to it yet, and there are no hyperlinks (as we do not need them here).

33. Cascading Style Sheet
33
The next component we need to make things interactive is a CSS. The name derives from the
top-down manner in which styles are defined. Properties for the entire page can be changed
for lower-level element types and even for individual elements on the page. The element
inherits the properties from the higher-level element but can override them (and pass them
down to its own children).

34. 34
The HTML page can be linked to a CSS that describes the formatting properties of particular
elements. In the CSS, there are various ways to address particular sets of elements, such as a
list item inside an ordered list (ol li). In the above example, each list item gets the left margin
of 20px. When the list item is in an ordered list it will have 10px padding at the top, whereas
the top padding is 0px for list items in an unordered list.

35. 35
The result of this CSS with the same HTML (well, we did put the link to the CSS in) in the same
browser is this. The browser takes the properties that are defined in the CSS to override the
default formatting properties for the HTML elements it finds.

36. Document Object Model
36
The DOM describes the organization of elements in your document on an abstract level. It
allows the browser to find all elements in a page and know which element is a child or parent
or sibling of another. The DOM is a universal roadmap for a structured document and allows
software to find their way around the contents of actual documents.

37. 37
Bringing HTML and CSS together taking the DOM into account. The CSS can pass properties
for particular elements in the document via their element tags, their location in the hierarchy,
their class attribute and/or their id attributes. This makes for a wide variety of formatting
that can be relatively easy controlled and assigned.

38. 38
The code shown on the previous page, viewed in a browser. The buttons in the menu bar are
activated or deactivated depending on where you are in my website. The language buttons
take you to the same page in another language. All styling is defined in the CSS.

39. JavaScript
39
JavaScript was developed to add interactivity to HTML pages. With JavaScript, contents of a
page can be changed without loading another page. Many properties of elements of the page
can be addressed and changed and actions can be linked to objects on the screen. This gives
us the interactivity we need to implement Progressive Disclosure.

40. 40
The JavaScript code can either be linked to the HTML page or embedded in a <script>
element. There is no functional difference between the two. The above code shows how a
piece of the HTML page is used as a trigger, and another piece is shown or hidden when the
trigger is clicked. Also, the text that serves as the trigger is changed by the JavaScript.

41. Drop-Down Content
41
The page shown in a browser. Clicking on “Show paragraph” makes the drop-down content
appear and changes the text of that paragraph. Clicking the paragraph again reverses the
action. Of course, nesting is an option as well: content in the hidden text may be used as a
trigger to show another piece of content, such as an image. Also, icons or images can be
used as triggers to reveal hidden content or hide it again.

42. Layered Content
42
With CSS3, layers were introduced. Basically, the 2D world of the screen turned into 3D at
that moment, as sections of the webpage were given an optional depth position index.
Placing a layer on top of others but making it hidden allows a trigger to make it appear. Don’t
forget to include a method to make it disappear again.

43. Making it Work
in Adobe RoboHelp HTML 10
43
Now that we have seen the basic principles at work in Progressive Disclosure (showing and
hiding content without leaving the page), let’s see how this can be implemented using Adobe
RoboHelp HTML. The tutorial includes a live demo, but this PDF includes screenshots of the
stages instead.

44. 44
Drop-Down Text
RoboHelp offers drop-down text since a long time. This was part of DHTML, an unofficial
extension on early HTML using JavaScript to make it work. With a little effort, you can get
around some of the shortcomings of this implementation and make it look like the goal we
set out to achieve.

45. 45
enter the always-visible text
RoboHelp HTML allows you to enter Drop-Down text in a small editor window. This is easiest
done when the disclosable text is not there yet. So we start with a topic with only the steps
that are shown when the page will be loaded.

46. 46
select the hotspot text
and create the drop-down
Select the step text and choose Create Drop-down Hotspot and Text from the DHTML menu.

47. 47
enter the drop-down text
A small editor window appears in which you can enter the text to be shown or hidden when
the trigger is clicked. The editor allows most of the actions you would do in the main editor
window, so you can insert images, links to other pages, and insert a nested drop-down text.

48. 48
click outside mini-editor
to hide the drop-down text
Click outside the mini-editor to close it. A disadvantage is that the drop-down text is no
longer visible in your source. The styling sort of indicates it, but might also be applied
manually or indicate a glossary term, a pop-up link or expanding text. It takes several clicks
to see the hidden content in your source material.

49. 49
drop-down text can be nested
It is possible to enter multiple levels of drop-down text. In the mini-editor, select the word(s)
that should work as the trigger and choose the Create Drop-down Hotspot and Text
command again. As far as I can tell, there is no limit to the nesting levels (but your users may
not like all the clicking).

50. 50
not only text can drop down
The mini-editor allows most functions that are normally available, so you can insert an image
instead of text (or use both).

51. 51
resulting WebHelp in a browser
The resulting WebHelp shows like this. The first and second step each have their substeps
hidden. Clicking the step opens and closes its substeps.

52. 52
resulting WebHelp in a browser
The drop-down text appears immediately after the paragraph that contains the trigger. In
this case, the image appears between the substeps. There is no way to change this in
RoboHelp.

53. 53
Triggers and Targets
RoboHelp has another method that should be covered here: triggers and targets. The names
were maybe not chosen very wisely, but let’s see how the implementation was done and how
it can help us achieve the goal of progressive disclosure.

54. 54
add target and trigger images
Start by adding the target (which must be an image or a table) to your source. Also add a
trigger (which must be an image) to the text line. I chose to add a small question mark at the
end of the first substep.

55. 55
select the trigger image
Selecting an image makes the so-called cable drum appear. The drum is green, meaning it is
not connected to a target yet.

56. 56
pull a link to the target
Drag the mouse from the cable drum to the target. When a valid target is reached, its
bounding box is shown in green. The target is selected when releasing the mouse.

57. 57
select the show/hide effect
Choose one of the available effects for the target appearance. I suggest NEVER using anything
other than Show/Hide. Your help system is not created for entertainment but for usefulness.

58. 58
ready to build the output
The target is marked as being connected to a trigger. Now we can build the WebHelp again.

59. 59
resulting WebHelp in browser
The resulting WebHelp page in a browser. The empty space is the space taken up by the still
invisible target.

60. 60
clicking the trigger makes
the target appear/disappear
Clicking the trigger image makes the target appear. Clicking again makes it disappear.

61. 61
Useless for my Goal
Since the target takes up space even when it is hidden, this feature is useless for progressive
disclosure. If RoboHelp would support layers, I could position the target on top of other
content so that there would not be empty space. But layers are not supported. Also, I cannot
use words or sentences as triggers, and I cannot use anything but images or tables as
targets.

62. 62
Perfecting the Appearance
Instead of words or entire sentences behaving like the hotspots, I wanted to use a number of
small icons. I could have chosen Wingdings or Zapf Dingbats, but I don’t want to run the risk
that an unavailable font causes garbage on the screen in your browser. Also, I want to apply
some background coloring and padding to the drop-down text to make it stand out.

63. Images ≠ Text
63
In RoboHelp, I can only use text as the hotspot for drop-down content. Images can only be
used as triggers for targets, and we’ve seen that this feature is useless for our goal. So how
do I get over this seemingly impossible dilemma?

64. 64
select icon image plus space
To change the drop-down hotspot into an image, insert the image but make sure to select
some text as well (otherwise, the Insert Drop-down Hotspot and Text command remains
disabled). A space in front of the image is all it takes to make it work.

65. 65
The mini-editor also allows formatting of the text that will be revealed, to make it stand out
from the surrounding text. All normal formatting options are available. This shows how to
add background color (shading) and padding to the drop-down text.

66. 66
final result in a browser

67. 67
Using Pop-ups
RoboHelp offers various ways of creating pop-up elements. These may be useful for
progressive disclosure as they do not take the user off the page - which is one of the
defining principles of progressive disclosure.

68. 68
Select a piece of text (use the trick with the space plus an icon image again) and select “Text-
only Pop-up” from the Insert menu. Pros: entering the text is done on the spot. Cons: no
images, no styling, no influence on anything except the text.

69. 69
The result is not overwhelmingly satisfying, but as noted you have no influence on the styling
(except if you to some heavy-duty CSS tweaking).

70. 70
The only other option is to first put the text (including the images, styling etc.) in a new topic
(to which you have to apply another master page to get rid of all kinds of auto-insertions by
RoboHelp - you may also have to define a separate CSS for this type of topic). Then create a
hyperlink to a pop-up. Optionally, you can set the size for the pop-up explicitly (but that
takes a lot of trial and error).

71. 71
Without the heavy-duty CSS work, the result, again, is not something that makes me very
happy. I seriously miss the layering techniques in RoboHelp. You could perhaps bring those
in via the CSS backdoor but that level of tweaking is beyond the scope of this tutorial.

72. Making it Work
in MadCap Flare 9
72
Note: the output shown in some of the following slides was created using a trial version of
MadCap Flare 9. The trial randomly changes characters in the output. This is not a bug in the
software or an effect of the techniques I have used.

73. 73
Drop-Down Text
First technique to be checked is, again, the drop-down text.

74. 74
enter the always-visible text
MadCap Flare offers the same Drop-down text option as RoboHelp HTML. To use this option,
I first create the text that should always appear on the page. These are the main procedure
steps.

75. 75
select the drop-down hotspot
Before adding substeps, I have to create a drop-down text placeholder for them. Select the
text that should become the trigger for the drop-down text to appear. Then make sure the
Insert ribbon is shown and select Drop-Down Text in the Text section of this ribbon. NOTE: it
has to be a <p> to work. You cannot create a Drop-Down Text when selecting a <li> or a
single word.

76. 76
Unlike RoboHelp HTML, the editor that appears does not allow entering the drop-down text
itself. It only allows selecting part of the already selected text as the drop-down hotspot. This
does make the dialog just a little superfluous. Just click OK to insert both the hotspot and the
drop-down placeholder text.

77. 77
drop-down text placeholder is added
MadCap Flare adds a so-called toggler image in front of the selected hotspot text and makes
the selected text appear as a clickable link. The drop-down placeholder text is shown directly
below the paragraph that holds the hotspot. This paragraph can now be edited.

78. 78
edit the drop-down text
The paragraph can be changed into anything, such as a bullet list or a complete section.

79. 79
build the primary output
Once the drop-down text is finished, select the Project ribbon and click Build Primary to
generate output.

80. 80
If the Build did not generate any errors, click View Output to see the resulting page in your
browser.

81. 81
resulting WebHelp in a browser
The first step with substeps in a drop-down section shows up like this. Both the toggler
image and the step text are clickable and make the drop-down text appear or disappear.

82. 82
resulting WebHelp in a browser
The toggler image is replaced by another one that shows the hidden content is now shown.

83. 83
Using Togglers
Instead of using the standard Drop-Down Text method, which has its limitations, MadCap
also offers a more intelligent way of changing the visibility of items on the screen. This is
done by inserting Togglers and connecting them to named elements.

84. 84
enter the target text for the toggler first
When using togglers, the destination for the toggler has to be available beforehand. So I
enter the substeps in step 2 first.

85. 85
set a name (identifier) for the target
The toggler is connected to the target by an identifier, which has to be set before I can link to
it. Select the entire element that should be shown or hidden, make sure the Home ribbon is
visible, and select the Name option in the Attributes section of the ribbon.

86. 86
Give the element an intelligible name, so that you will be able to find it later, when linking the
right toggler to the right target.

87. 87
flag symbols indicate named elements
The unordered list with substeps is now named. This is shown by a flag symbol (which does
not appear in the output).

88. 88
set the location to insert the toggler
I want to add the toggler at the end of the step, so I place the cursor there. Make sure the
Insert ribbon is visible and select the Toggler function in the Text section of the ribbon.

89. 89
The Toggler mechanism inserts a pretty stupid text “Click Me!” and allows you to point to the
named target that should be shown or hidden when the toggler is clicked. Do not worry
about the text at this point, as it remains editable and we will replace it with an image in the
end. Click OK to insert both the toggler image and toggler text and link it with the named
target. The properties of the named target are set accordingly.

90. 90
replace “Click Me!” but leave one space
To replace the stupid “Click Me!” toggler text with an image, you have to take a little care.
Selecting the entire text and then inserting an image (replacing the selected text) removes
the toggler as well. You can either insert the image first and then remove the text or remove
the text but leave at least one space before inserting the image.

91. 91
insert the icon image in the toggler
The image is now shown next to the toggler image. Switch to the Project ribbon to generate
the Primary Build again.

92. 92
resulting WebHelp in a browser
The resulting page in my browser. Both the toggler image and my own image are shown at
the end of the step.

93. 93
resulting WebHelp in a browser
Clicking either the toggler image or my own image (or the space inbetween) makes the
hidden text visible. Note that with this mechanism, the hidden text does not have to be
immediately below the toggler, as is the case with Drop-Down Text.

94. 94
Toggler hotspots and targets can be nested, as shown in the above example. Each element
that shows a flag is a potential target.

95. 95
Each toggler can be connected to one or more targets. This allows having one global “Show/
hide all substeps”, or allowing the user to select their expertise level with just one click.

96. 96
final result in a browser

97. 97
Perfecting the Appearance
Even though the automatic toggler images are not completely off the mark, they are all the
same. I want to use the image to indicate the type of information to be disclosed. So I added
my own icons. This makes the togger images obsolete - so I need to make them go away.

98. 98
edit the Master Stylesheet
The automatic toggler images must be removed in the Master CSS. This can be opened via
the Project ribbon.

99. 99
Scroll down the Styles list and select the “MadCap | toggler” class. The properties are shown
to the right (choose “Show Assorted Relevant Properties” above the list). Make sure both the
“mc-open-image” and the “mc-closed-image” are set to (none). Save the style sheet and
rebuild the target to see the effect of this change.

100. 100
resulting WebHelp in a browser
This is the resulting page in my browser. Note that the toggler image for the drop-down text
is not changed, only the one for the toggler hotspot has been removed. My image now
functions as the hotspot.

101. 101
resulting WebHelp in a browser
Clicking the hotspot image makes the target element visible. Clicking it again hides the
target element. The element can be anywhere on the page, as the toggler is linked to the
target via identification.

102. Conclusions
Pros, Cons and Feature Requests
102
My conclusions are based on this trial in making progressive disclosure work only. For all
other purposes, there may be other lists of strengths and weaknesses. Also, I must note that I
have slightly more experience in using RoboHelp than I have in using MadCap Flare.

103. Drop-down text editing
Multi-screen target builds
Control over positioning
Pop-ups
Triggers and targets
Layers instead of pop-ups
103
RoboHelp HTML 10

104. Changes to CSS
Togglers
Showing/selecting blocks
Moving content around
Pop-ups
Layers instead of pop-ups
104
MadCap Flare 9

105. Questions ?
www.writeless.eu
www.jang.nl
jang@jang.nl
4everJang
blogs.jang.nl
105
If you need more info, advice, or training on any of the aspects covered in this tutorial, feel
free to contact me. I offer in-house training and I do projects covering all aspects of bringing
valuable information to users in a minimalist paradigm - maximizing the usefulness.