Blog Archives

REST API documentation embedded in the application

Our development team has built a tool that documents an application’s REST APIs within the application itself. What’s more, you can test the REST resources and methods too. All from the application’s user interface. Now, that’s embedded help for nerds. 🙂 I’m writing this post because I think many technical writers and developers will be interested in this solution. It may trigger ideas about adding something similar to other applications too.

The tool is called the REST API Browser, and it is implemented as a plugin. At the moment, it is available only within the Atlassian Plugin SDK. In the future, you may be able to download the REST API Browser as a separate plugin and install it into any Atlassian application.

So, what does the REST API Browser do, what is the Atlassian Plugin SDK, and how can you get the REST API Browser to work within an Atlassian application?

Overview of the REST API Browser

This is what the REST API Browser looks like, when running inside an application called JIRA:

The /user/search REST resource in JIRA

JIRA is an issue tracker developed by Atlassian. The above screenshot shows one of the JIRA administration screens, part of the application’s user interface. I’m running JIRA on my local machine, in plugin development mode. The REST API Browser is available as one of the options on the application’s administration screens. It’s as simple as that.

In the screenshot, you can see the resources in the JIRA REST API, starting at the /user/search resource. For each resource, the REST API Browser shows the methods (GET, POST, PUT) and the parameters available.

You can even do real-time testing of the APIs, by submitting a request and seeing the response. In the screenshot below, I have run a GET request using the /user/search resource, asking for details of username “admin”. You can see:

  • A form, prompting you for the parameters relevant to the resource and method. In this case, the only parameter is the username.
  • The request, as formulated by the REST API Browser.
  • The response headers.
  • The JSON in the response body.

A REST request and response

The application’s REST APIs at your fingertips!

Which REST APIs does the Browser show?

The REST API Browser displays all the REST and JSON-RPC APIs available in the running installation of the application. That means all the remote APIs that are part of the application’s default installation (JIRA, in this case) as well as any additional REST APIs provided by a plugin.

So, if you install a plugin into JIRA, and that plugin exposes a REST API, the resources will show up in the REST API Browser too. Magic.

Introduction to Atlassian Plugin SDK

The Atlassian Plugin SDK is a tool for developers who want to create a plugin (add-on) for an Atlassian application. For example, you may want to add a new option to the Confluence page menu, showing all authors who have ever updated the current page. Or you may want to add a new option in JIRA that points to your organization’s intranet site.

But the SDK is useful even for people who don’t want to build a plugin. You can use the SDK to download and run an Atlassian application on your own machine, in plugin developer mode. One of the features that you get is the REST API Browser.

How can you get hold of such sweetness?

Here’s a quick start guide. First, install the SDK and use it to download and run your application:

  1. Follow the guide to installing the Atlassian Plugin SDK. Do just steps 1, 2 and 3. You can skip the last step, which sets up an IDE (Eclipse, IDEA or NetBeans), if you do not need a development environment.
  2. Create a directory in your file system to store the application executables. Let’s assume you want to run the REST API Browser in JIRA. Then, for example, you could create a directory called myjira.
  3. Open a command window.
  4. Go to the new directory that you just created, myjira.
  5. Run atlas-run-standalone --product APPLICATION. For example, atlas-run-standalone --product jira.
    Note:
    There are two dashes in front of the word product.

After following the above steps, you will have the application running on your computer. When all the downloads and installation are complete (which may take a while), you will see a message in your command window that includes the URL for the local installation of the application.

For JIRA, the message will look something like this:

[INFO] jira started successfully in 174s at http://localhost:2990/jira
[INFO] Type CTRL-D to shutdown gracefully
[INFO] Type CTRL-C to exit

Now you can access the application in your browser and use the REST API Browser from the application user interface:

  1. Go to your web browser and enter the URL given for your application. For example, http://localhost:2990/jira.
  2. Enter the username and password: admin / admin.
  3. Go to the application’s administration screen. For example, in JIRA: Click Administration at top right of the screen.
  4. Click REST API Browser on the administration screen.
  5. Choose an API from the dropdown list at the top left of the screen.
  6. Choose a resource from the list on the left of the screen.
  7. See the methods (GET, POST, PUT, etc) and the parameters available for that resource.
  8. To test the resource, enter the parameter values as prompted then click Execute.

The documentation has the details of running the REST API Browser in the SDK, and of viewing and testing the resources.

Getting technical: How the REST API Browser works

The source code is available on Bitbucket, as part of the Atlassian Developer Toolbox. The developer’s guide describes how to ensure that a REST API is included in the Remote API Browser. That document also gives a summary of how the browser is put together.

Pretty neat, huh

From a plugin developer’s point of view, the REST API Browser is very useful. From a technical writer’s point of view, I think it’s pretty revolutionary. Has anyone seen other examples of embedded REST API documentation?

Kudos to Rich Manalang and the Atlassian developer relations team for developing this shiny tool. Here is the blog post in which Rich announced it: Introducing the REST API Browser and the Atlassian Developer Toolbox.

Advertisements

Wiki documentation – Splunk on MediaWiki

This week I had the privilege of being given an expert guided tour through a technical documentation site running on MediaWiki. It’s a very cool site. These are the notes I wrote up after the session. I hope you find them useful! It was very interesting for me to have such a detailed look at documentation running on a wiki other than Confluence.

Rachel Perkins walked us through the Splunk product documentation, running on a customised MediaWiki platform. She and the rest of the Splunk documentation team have designed customisations to support their requirements. As well as the tools visible to the general reader on the documentation site, Rachel has added tools that make life easier for the authors on the wiki. In particular, authors can define the product manuals, tables of contents and product versions in text files, with metadata associated with each manual and version. Writers can also branch and inherit documents when a change is required for a specific product release.

Walkthrough of Splunk documentation on wiki platform - MediaWiki

Splunk docs home page

First impressions

Here are a few of the things that struck me about the site, even before Rachel walked us through it:

  • splunk>docs: What a cool name!
  • A very solid, comprehensive documentation site.
  • Left-hand navigation bar showing table of contents.
  • Feedback form at the bottom of each page, asking “Was this documentation topic useful?
  • Navigation at the bottom of each page, pointing to the start of a section and the next topic.
  • PDF export option available on every page.
  • Tool at the top allowing you to select the product version and manual that you want.
  • Some user comments on the pages, but not very many. (Rachel later explained that they would like to encourage more comments. She wonders if the blue line at the bottom of the page discourages readers from scrolling further down.)
  • A separate wiki for general discussion and community input.
  • A section called “Hot Wiki Topics” at the top left of the wiki pages.

The walkthrough

Rachel explained that the primary goal in selecting MediaWiki as their platform was to make the documentation as collaborative as possible. This platform made that easy. It is also important that there is a lively community of developers.

The authors value the “live” aspect of the wiki. The content is immediately available, as soon as you save it. At first, authors were a little disconcerted that there was no lengthy publication process. Rachel estimated that it took about two months for them to get over their apprehension. The advantages are that readers always have the latest information, and writers can fix problems at any time. Rachel monitors all updates via RSS feeds, which are a standard feature of MediaWiki.

Walkthrough of Splunk documentation on wiki platform - MediaWiki

A page in the Splunk docs

Features:

  • PDF exports. All manuals are available as PDF files. Customers can generate them on the fly, for the entire manual. The way it works is that the tool caches the PDF file and serves it up to each reader. It only regenerates the PDF file if there has been a change to the content. This functionality is provided by an open source plugin that Splunk has customised. PDF versions of the manuals are very popular.
  • Documentation structure. Splunk have added wiki customisations to support the division of documentation into manuals, chapters and pages. To create the structure, writers edit a text file. One text file defines the list of manuals shown in the dropdown list at the top of the screen. Another text file defines the table of contents of each manual. If you load that page in view mode, you can click through from the table of contents to each page. If the page does not exist, then the tool creates a new shell page and populates it with template content.
  • Versions. Similarly, there is a text file to define the versions of the product. Each version has metadata that defines its status, such as released and unreleased.
  • Branching and inheritance. What is branching? Let’s assume you need to change a page because the functionality it describes has changed in the latest release. You would then branch the page, so that you leave one branch documenting the earlier version of the product and another branch for the new version. One page can apply to many versions. You can branch a page, a set of pages, a manual or the entire documentation suite. Splunk have created a tool called the “Branch and Inheritance Console”, where you choose the version you are branching from and to, choose the manual or pages that you want to branch, and then complete a number of selection fields to create the branch. There is no awareness of the content itself. So, for example, if you change the content of an earlier version, you may need to apply the same change to the later versions too, and you would have to do that manually. Note that a page may or may not need changing for a particular version. Note from Sarah: This is very neat! Permission control (via MediaWiki’s access groups) is by version. The general public will only see the newest version when you change its status to released. Everyone can see the versions numbers across the top of the page, indicating which version(s) the page applies to. This means that all contributors know which version to edit.
  • Context-sensitive online help. This is another wiki customisation, done via tags (labels) on the pages. Each page can have any number of tags, and those tags form a kind of unique help ID for the page. Rachel recommends a minimum of three tags to ensure a unique combination. There is a file that maps the tags and product version on the page to the link from the application screen. This means that writers can move and rename documentation pages without changing the help links in the product. If a help link points to a non-existent mapping, it goes to a default page.
  • Search. The search backend is a wiki customisation. They use the Google Mini Search Appliance. Rachel wants to improve aspects of the search, for example it does not recognise word stems. It’s pretty neat, though. It returns results for the version that you are currently in, or for the latest version if none is specified. Splunk uses the same backend for all its sites, not just the documentation. This means that you see search results from various sites, such as the documentation and the wiki, all on one search results page. A very nice feature is the “Search tips” panel that appears at the top of the search results sometimes. Rachel’s team have written a paragraph of tips that matches certain search terms, and will appear in the panel if someone searches for a matching term. People really like this, Rachel says.
  • Feedback form. There is a feedback form at the bottom of each page, asking “Was this documentation topic useful?” The resulting feedback is mailed directly to the documentation team. Each team member responds if they have something useful to say. They love getting this feedback. The tool does not use any external service to collect the feedback. Rachel is not sure whether it is part of MediaWiki or a plugin.
  • Left-hand navigation bar. This is a customisation, not a standard part of MediaWiki.
  • New version of the platform. Rachel and the team are working on a 2.0 version of the platform. It will support multiple products (currently it only supports one) and will have a new look and feel.
Wiki documentation - Splunk on MediaWiki

Search results showing a custom search tip at the top

Rachel mentioned that she is very happy with the documentation platform. I am very impressed too. 🙂

Splunk is in the process of making the customisations (all except the search) available as an open source project, headed up by Taylor Dondich.  The open source project, not yet publicly available, has a working name of “Ponydocs“. Cute!

Thank you so much for a great walkthrough, Rachel! And congratulations to the Splunk team for this excellent set of documentation.

WritersUA 2011 – Best practices for embedded UA

This week I attended the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. On Wednesday Scott DeLoach presented a great session called “Best practices for embedded UA“. This blog post is derived from the notes I made during the session. If you find any inaccuracies, they’ll be mine.

Scott gave us a set of guidelines for writing embedded user assistance (that’s help text and other information that appears as part of the UI) and showed us a number of sites that follow those best practices. He gave us guidelines on:

  • Writing the content of the user assistance
  • Getting user feedback
  • Allowing users to customise the user assistance they see
  • Encouraging users to learn
  • Using HTML5

Writing the content of the user assistance

In this section Scott focused on three things:

  • Persuading, motivating and communicating
  • Remembering that writing is a conversation
  • Integrating content from other sources

The Bank of America‘s online credit card application form is a good example of persuading and motivating.

  • At the top, the wording sets the expectation of time, telling you that you will receive a response in 60 seconds.
  • They point out that the communication is secure, which is a big concern of many customers.
  • When asking about citizenship/residence status, they give you a link called “Why do we ask for this?” That’s just the question people are likely to ask.
  • On the right, a panel contains a list of more questions that people are likely to ask. Instead of per-field help, the questions are much more advanced.

Restaurant.com is a good example of using writing as a conversation. This site can take advantage of the fact that the interaction is a more friendly one and a less formal one than online banking. For example, the popup on the password box says “Shhhhh! Your secret’s safe with us” before giving help on how to find a forgotten password. It’s OK to be fun and informal when the situation allows it.

Scott showed us a screenshot from Dreamweaver CS5, a good example of integrating content from other sources. At the bottom of the screenshot is a tab labelled “Reference”, where they integrate content from O’Reilly. You don’t have to write all your content. If content from other sources is good, use it.

Getting user feedback

Scott covered the following areas:

  • Allowing users to add comments
  • Providing alternative UA options
  • Requesting feedback
  • Ranking popular topics

An example from msdn.microsoft.com illustrated how you can allow users to add comments, and how useful this can be. There’s a section called “Community Content” where people can add their own information. This is really useful information, and is not filtered by Microsoft. The contributed information that Scott showed us was slightly critical about a feature provided by Microsoft, but the information was also really useful to other users.

The American Express gold card online application form is good at providing alternative UA options. There’s an area on the right called “Have a question? We can answer it right now,” showing a photograph of a smiling person. Scott says that the website will only show this particular text if the online support people are available right now to chat. Otherwise it will say something like, “Send an email”.

Some people don’t want to use the online information. They have the option to print the information, or to chat to someone on the phone. Not everyone is comfortable with using computers.

Talking about requesting feedback,  Scott showed us an example of a feedback form from msdn.microsoft.com, where people could fill in two yes/no answers, a graded answer (“how useful was this topic”) and a free-form text box. Scott remarked that it was a good form, because it only asked a few questions.

Scott really likes the example he showed us of ranking popular topics. The example came from Apple’s tech support knowledge base. They use scripting to find out which parts of the knowledge base people go to most often, and then they list the most popular topics. Scott likes the accessibility of this, and the wording – the use of the word “popular”, which makes readers feel good even if they’re looking for the answer to a problem. Also, what Scott finds the most impressive, is the “top searches” section. This is a great way to teach people how to do more complex searches.

Allowing users to customise the user assistance they see

Scott covered ways to allow users to:

  • Select a language
  • Ask their own questions
  • Reuse content
  • Turn off automatic user assistance

An example from the Carnival ship shows the usefulness of allowing users to select a language. The page Scott showed us is only visible once you have already booked in for a cruise. The site does a good job with callouts, per field, such as username and password. They explain the logic of the field and give you an example. There’s a lot of instructional information. You can choose another language, and everything on the page is translated, including the instructional text.

Scott remarked that he would prefer a bad translation rather than nothing. Even a part translation, or a Google translation, is better than nothing at all. Let people know that you’re using some sort of machine translation. They’ll be grateful for anything at all.

Another example showed a technology that we can use: Google’s translation API. Scott gave us this URL as an example: img.labnol.org/files/translation.html

From Sarah: I’ve done some searching and found some useful blog posts about this technology and how to use it without going to Google itself: How to Translate PDF & Word Documents with Google Translation, and Add Language Translation to your Website – Tutorial.

Scott noted that these technologies are improving all the time. Compare them to OCR technology, which was horrible at the start but is now really good. Big companies like Google are spending a lot of time on such technology and we should keep an eye on it.

On the subject of allowing users to ask their own questions, Scott showed us an example from the Washington Post website. In the example he showed us, you could highlight a term (such as a person’s name) and see a popup containing additional information about that term or person. This is similar to Netflix, when you hover over a movie. The Washington Post site uses an application called Apture to make this happen.

Users are beginning to expect this sort of rapid information. We should provide it too.

Scott showed us an example from MadCap’s software knowledge base, to illustrate how we can allow users to reuse content. MadCap provides a number of buttons for Twitter, Facebook, Favourites and Print. You can reuse the content in Twitter and Facebook. People want to do this sort of thing, so we should provide them with the opportunity. Also, who knows what people will do when we provide these features? People start using them in all sorts of creative ways.

A lot of people, especially the expert users, want to turn off the automatic user assistance. Some people like to learn by doing it on their own. Some people get very frustrated if we constantly try to help them. Give them a way to turn it off. For example, eBay has the option “Don’t show me this again”.

Encouraging users to learn

Scott spoke about these techniques:

  • Encouraging success
  • Encouraging exploration
  • Challenging people

If new users find that they can do something immediately, that’s essential for their success.

An example from Windows Live: Signing in to the Microsoft sites, the first thing you do is create a password. They tell you about the strength of the password, and a graphic representation of how strong your password is. You feel like you’ve achieved something if your password gets the green light.

Scott showed us a travel website, kayak.com, that is great at encouraging exploration. The site has nine areas. Typically, most people go to only specific parts of the sites, such as car hire, flights, and so on. There’s a link that encourages you to spend a few minutes exploring the other features, to find awesome travel deals. There’s also a graphical representation of how much of the site you have explored so far, encouraging you to try new parts of the site.

An example from Intuit shows how you can challenge your users. They display a daily quiz for the “educated investor”. As you’re going through the site, you notice the question. Just one question per day. It motivates you to see if you can answer it correctly, check your answer, then even come back the next day for the next question, and get more involved in the site.

HTML5 techniques

Scott talked about:

  • Adding subtitles to instructional videos
  • Forms
  • Editing content
  • Saving content

Subtitling is Scott’s favourite, the feature he thinks is coolest. Subtitle files are “.srt” files. If you have a foreign-language movie that you’ve downloaded, do a Google search for the related “.srt” file. Put the file in the same folder as the AVI or MPEG file, and the player will usually find it.

Now, with HTML5, you can write a .srt file yourself. They’re very easy to write, says Scott. Then you can integrate it into your movie.

In HTML5, add the “video” element to include your video on the page. Include two script elements and a div

See Jan Gerber’s jQuery-based script to match an srt subtitle document to an HTML5 video:

When designing HTML forms:

  • You can have fields that are required, using the “required” attribute.
  • Validating input fields. You can give fields a type, that will prompt automatic validation. You can also build your own validation.

You can allow users to edit the content of a web page. Specify a new attribute, *contenteditable=”True”*. You can apply the attribute to any element, such as a paragraph. People can then click the content in that element and change it.

You can then save the edited content. Scott showed us some sample code. Typically, you’re saving it to the user’s local computer. The mechanism is similar to cookies, but much larger.

In a previous blog post, I covered some of this material from Scott’s earlier talk on HTML5: WritersUA 2011 Tuesday – HTML5.

My conclusion

Thank you Scott for yet another information-packed, engaging session!

WritersUA 2011 Monday – Adobe RoboHelp’s commenting feature

This week I’m attending the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. One of the sessions that I attended today was an Adobe lab, run by Scott DeLoach, Kevin Siegel, Laurie Edelman and others.

During the conference, there were a number of “lab” sessions. The labs offer a number of computer workstations and software that we could use for hands-on experimentation. A few experts wandered around offering help and advice.

My aim in attending the Adobe lab

I decided to take a look at the latest version of RoboHelp. I have used RoboHelp extensively in the past, but not since RoboHelp 8.

In particular, I wanted to explore the new features in RoboHelp that allow you to gather feedback from users, and allow users to share comments among themselves. I had heard and seen this demonstrated in various places. The idea is that you have an online help system, shared amongst your users, even installed individually on their machines. Each user can add comments to their own version of the help, and share those comments with other users via a central server.

Exploring RoboHelp’s comments feature

In the lab there was no RoboHelp Server available, so we could not see the server side of the functionality in action. But I did manage to explore how it would work. Here’s what I did.

In RoboHelp, create your online help topics as usual. For the lab session, I used one of the sample projects supplied by Adobe.

The next step is to generate your help output, selecting Adobe Air as your output format. The Adobe AIR output is the only format that supports comments submitted by users. To generate the AIR output:

  • Choose one of the a “single source layouts” available. A single source layout basically corresponds to an output format. For this lab session, a few Adobe Air layouts were available. I chose “Adobe AIR – Role Based”.
  • Double-click the layout in the “single source layout” window. You get a popup where you can configure various options for the chosen layout.
  • On the “General” tab, choose an “Output Type” of “Adobe AIR Application“. This is the only output type that will allow comments from users. The other output types are hybrids that weave a Flash solution into an HTML web-based help system.
  • You will need a digital certificate. If you don’t have one (which is likely at this point!) you can generate a self-signed certificate for use while testing. Eventually you will need to get a certificate from a real certificate authority (CA). To generate a digital certificate, click “Create” next to “Digital Certificate”.
  • Supply a publisher name of some sort.
  • Specify a password for the certificate.
  • Next to “Save As”, specify a path and name something like “C:\cert.p12”.
  • Click “OK” to generate the certificate.
  • Click the “Collaboration” tab.
  • Select “Enable Topic Rating”, “Enable Commenting” and “Enable Comment Moderation”.
  • Set a password that the comment moderator will use.
  • At this stage, it would be good to specify the RoboHelp server to enable server-based storage and sharing of comments. I could not do this during the lab, because there was no RoboHelp server available.
  • Click “Save and Generate” to create your online help system.
  • Click “View Result” to see the resulting help files.

The AIR application will start up, showing your help topics in the help system. Now you want to add a comment to a topic.

  • Click the comment icon near the top left of the screen. (The icon looks like a couple of comment bubbles.)
  • A comment area will appear at the bottom of the topic.
  • To add a comment, click the plus sign.

Adding a comment:

Adobe RoboHelp's commenting feature

Adobe RoboHelp's commenting feature

Comments are displayed in reverse chronological order:

Adobe RoboHelp's commenting feature

Adobe RoboHelp's commenting feature

My conclusion

This looks pretty cool. As far as I could see, there’s no opportunity to add graphics or formatting to the comments. They’re plain text. Also, they’re not threaded – you can’t reply to a specific comment. Still, once a server is hooked up it is pretty cool for people to be able to share comments from their desktop apps. I’d be interested to see it in action, and to hear any experiences other technical writers may have had with this feature.

WritersUA 2011 Monday – Hotrodding your online help

This week I’m attending the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. These are my notes from the session called “Hotrod My Help” presented by Leah Guren. If you find any inaccuracies, they’ll be mine.

Leah’s presentation style is both informal and professional. She started out by introducing herself as “this deranged woman”. She then became more serious quite quickly. Her talk was about design of online help systems. She used the metaphor of hot rodding – talking about the paint rather than what’s underneath.

Introducing the topic

Leah’s talk was entirely tool agnostic, and described techniques that we can apply to our documents with very little effort.

Nevertheless, Leah pointed out, this stuff matters for a number of reasons:

  • Design should match the subject matter.
  • Better design improves usability.
  • We’re not talking about making things look pretty. We want to make sure that what we develop will communicate as effectively to users as the words we choose.
  • When people see help with a sloppy design, they’re less likely to trust the information.
  • Design should support the meaning of the content.
  • It should make it easier for people to find what they’re looking for, to recognise it and to use it.

Leah also pointed out that if your readers are noticing the design, then you have made a mistake. (As a side note, I tweeted this point and received an interesting reply from Bill Kerschbaum.)

The design concepts

Leah introduced us to some design concepts, the jargon. Mastering the terminology lets you defend you choices with more authority.

Leah introduced us to the acronym PARCH:

  • Proximity – When elements are close together, we recognise that they are related.
  • Alignment – Choose where you position elements on the screen, to develop a meaningful design.
  • Repetition – Repeated visual patterns help people to access and remember the information efficiently.
  • Contrast
  • Hierarchies and dependencies

Proximity

One stylistic mistake that violates this principle is the “floating heading”. That’s when you have a heading with the same amount of space above it as below it. Instead, there should be less space below the heading, to bring it closer with the content it describes.

Alignment

Use alignment for a less sloppy design.

Repetition

Consider things like colours, icons, placement.  Stylistic repetition reinforces the information for the user and gives them more confidence.

Contrast

We need contrast so that people can see the differences in meaning between different elements on the page. For example, links should look different from other text. So should headings, and layered information. The rule of contrast is that it must be meaningful. Readers don’t care how you do it, whether you use a list or headings or bold text. Just be consistent and make it meaningful.

Hierarchy

This defines how elements of information on the page are related to other elements on the page. Consider the use of white space and indentation.

Other concepts and techniques

  • White space – Consider margins, space between lines, hanging indents, paragraphs etc. White space is critical. If you don’t have enough white space, the text is not readable. Users flee from densely-packed screens.
  • Plumb lines – Draw vertical lines at every point where an information element starts, to make a clean design. Good clean design steps into the background. Bad design is noisy.
  • Indents and text wrap – Indents help the concept of contrast. Good examples are bulleted lists.
  • Paragraphs – Leah recommends the following design techniques for paragraphs, to enhance readability:
    • Flush left, ragged right.
    • Single line spacing.
    • White space between paragraphs.
  • Chunking – Use white space intelligently, to show the logical visual chunks of information.
  • Nesting – Nesting relates to hiearchies and logically related information. Leah mentioned “illegal” nesting. The rule in technical communication (a tacit contract with the user) is this: if I’m going to break the information down into logical categories, there must be more than one category. For example, you can’t have just one item in a bulleted list, or just one level-2 heading.

Examples – applying the concepts

After introducing all the theory, Leah moved on to examples of web page makeovers, using her hotrod metaphor. She took us through some real documentation and web pages from various sites, and applied her principles to each one.

These are some of the mistakes she fixed up:

  • Messy text.
  • Dashboard that was not designed to be meaningful.
  • Screenshots taken without care and without tidying up afterwards.
  • Sloppy text wrap, that probably happened when pasting content from elsewhere.
  • Inconsistency in capitalisation, punctuation, and so on.
  • Long lines that force the user to do horizontal scrolling. A typical culprit here is information in tables. This is easy to fix, but easy to overlook.
  • No visual cue that content continues below the fold. Readers may think they have reached the end of the steps, without realising they need to scroll down. One way to fix this is to include a “Start” and “End” icon.
  • Help window opening on top of the application by default. The solution is to make the default opening position at top right, for example.
  • Concordance (repetition of same words) in the table of contents (toc). This is very distracting. If the toc entries are very long, people will not see the meaningful bit in the toc window.
  • Use of blue (usually used to denote hyperlinks) as an emphasis or point colour.
  • Too many layers of hierarchy (too much nesting) in a table of contents.
  • Links in the text. Don’t put links in the text unless they’re popups or dynamic HTML. Keep all links off to the side or at the bottom. People get distracted by links, or click them and get lost.
  • Empty topics.

Help authoring tools

If the problem we’re addressing lies within a tool that we use to develop help systems, then the HAT and DITA tool developers need to fix it. We need to be involved in the design of such tools.

My conclusions

Throughout the presentation, Leah had “bonus rounds” where she asked us to name concepts that the pages were violating. She promised us “valuable prizes” (said with a grin) which we could collect afterwards. This was great for getting audience participation going.

Thank you for a lively session, Leah!

Hotrod My Help
=============
Leah Guren (Cow TC) 

http://www.cowtc.com/

Leah started out by introducing herself as “this deranged woman”. Herpresentation style is informal and easy. She then got more serious quite quickly. She does many presentations about tehcnical communication. Today she will talk a lot about deisng. Use the metaphor of hot rodding – talking about the paint rather than what’s underneath.

Everything she will talk about is tool agnostic. These are techniques that you can apply to your documents with very little effort.

This stuff matters because the design should match the sujbect matter. Better design improves usability. we’re not talking about making things look pretty. We want to make sure that what we develop will communicate as effectively to users as the words we choose.

When people see help with a sloppy design, they’re less likely to trust the information.

If your readers are noticing the design, then you have made a mistake.

Good design follows a series of rules.
Design should support the meaning of the content.
It should make it easier for people to find what they’re looking for, to recognise it and to use it.

Leah introduced us to some design concepts – the jargon. Mastering the terminology lets you defend you choices with more authority.

Leah introduced us to a new acronym: PARCH:
* Proximity – When things are close together, we recognise that they are related.
* Alignment – Choose intential places to position elements on the screen, to develop a meaningful design.
* Repetition — Repeated visual patterns help people to access and remember the information efficiently.
* Contrast
* Hierarchies and dependencies

Proximity:
==========
One stylistic mistake that violates this principle is the “floating heading”. That’s when you have a heading with the same amount of space above it as below it. Instead, there should be less space below the heading, to bring it closer with the content it describes.

Alignment
=========
Less sloppy design.

Repetition
==========
Consider things like colours, icons, placement.

Stylistic repetition reinforces the information for the user and gives them more confidence.

Contrast
========
We need contrast so that people can see the differences. For example, links should look different from other text. So should headings, and layered information. The rule of contrast is that it must be meaningful. Readers don’t care how you do it, whether you use a list or headings or bold text. Just be consistent and make it meaningful.

Hierarchy
===========
This defines how elements of information on the page are related to other elements on the page. Consider the use of white space and indentation.

Other concepts:
==============
* White space — Consider margins, space between lines, hanging indents, paragraphs etc. White space is critical. If you don’t have enough white space, the text is not readable. Users flee from densely-packed screens.

* Plumb lines — Draw vertical lines at every point where an information element starts, to make a clean design. Good clean design steps into the background. Bad design is noisy.

* Indents and text wrap — Indents help the concept of contrast. Good examples are bulleted lists.

* Paragraphs — Leah recommends the following design techniques for paragraphs, to enhance readability:
** Flush left, ragged right.
** Single line spacing.
** White space between paragraphs.

* Chunking — Use white space intelligently, show that we’re showing logical visual chunks of information.

* Nesting — Nesting relates to hiearchies and logically related information. Leah mentioned “illegal” nesting, which all of us do. The rule in technical communication (a tacit contract with the user): if I’m going to break the information down into logical categories, there must be more than one category. For example, you can’t have just one item in a bulleted list, or just one level-2 heading.

Examples – applying the concepts
========

With the theory out of the way, Leah moved on to examples of makeovers, using her hotrod metaphor. She took us through some real documentation and web pages from various sites, and applied her principles to each one.

Some of the mistakes she fixed up were:
* Messy text.
* Dashboard that was not designed to be meaningful.
* Screenshots taken without care and without tidying up afterwards.
* Sloppy text wrap, that probably happened when pasting content from elsewhere.
* Inconsistency in capitalisation, punctuation, and so on.
* Long lines that force the user to do horizontal scrolling. A typical culprit here is information in tables. This is easy to fix, but easy to overlook.
* No visual cue that content continues below the fold. Readers may think they have reached the end of the steps, without realising they need to scroll down. One way to fix this is to include a “Start” and “End” icon.
* Help window opening on top of the application by default. The solution is to make the default opening position at top right, for example.
* Concordance (repetition of same words) in the table of contents (toc). This is very distracting. If the toc entries are very long, people will not see the meaningful bit in the toc window.
* Use of blue (link colour) as a highlight colour.
* Too many layers of hierarchy (too much nesting) in a table of contents.
* Links in the text. Don’t put links in the text unless they’re popups or dynamic HTML. Keep all links off to the side or at the bottom. People get distracted by links, or click them and get lost.
* Empty topics.

Help authoring tools
====================

If the problem lies within a tool that we use to develop help systems, then the HAT and DITA tool developers need to fix it. We need to be involved in the design of such tools.

My conclusions
==============

Throughout the presentation, Leah had “bonus rounds” where she asked us to name concepts that the pages were violating. She promised us “valuable prizes” (said with a grin) which we could collect afterwards. This was great for getting audience participation going.

Thank you for a lively session, Leah!

%d bloggers like this: