progressive disclosure - putting the user in control

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.

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.

Progressive DisclosureSome 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.

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

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

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

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

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

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

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

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

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.

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

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

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.

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

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

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

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

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

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

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

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

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.

MinimalismMain 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.

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.

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.

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.

Dynamic HTMLHTML, 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.

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

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

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).

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

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

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.

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

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

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.

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

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.

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.

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.

Making it Workin 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

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

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

select the hotspot textand create the drop-down

Select the step text and choose Create Drop-down Hotspot and Text from the DHTML menu.

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

click outside mini-editorto 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

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

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

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

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

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

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

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

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

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

ready to build the output

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

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

clicking the trigger makesthe target appear/disappear

Clicking the trigger image makes the target appear. Clicking again makes it disappear.

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

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.

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

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

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

final result in a browser

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

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

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

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

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.

Making it Workin 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

Drop-Down Text

First technique to be checked is, again, the drop-down text.

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

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

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

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

edit the drop-down text

The paragraph can be changed into anything, such as a bullet list or a complete section.

79

build the primary output

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

80

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

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

resulting WebHelp in a browser

The toggler image is replaced by another one that shows the hidden content is now shown.

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

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

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

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

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

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

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

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

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

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

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

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

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

final result in a browser

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

edit the Master Stylesheet

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

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

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

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.

ConclusionsPros, 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.

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

Changes to CSS

Togglers

Showing/selecting blocks

Moving content around

Pop-ups

Layers instead of pop-ups

104

MadCap Flare 9

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.