DITA topic

Topics are the primary way we deliver content to users. Include topics for all product functionality available to users and partners.

Clear purpose

Make sure that each topic has a clear purpose, explained in the opening paragraph. This helps users scan quickly to determine whether the topic contains the information they need.

Meaningful content

Each topic should have meaningful content. Keep user goals in mind, and focus your effort on developing content that helps users achieve those goals. Write less about what the product can do, and more about why the user cares (the use case) and how to be successful.

If there are multiple ways for the user to be successful, document only the best-practice, recommended way.

Avoid using a topic purely a parent to provide structure to child topics. Ensuring that each topic has meaningful content helps limit the number of clicks the user needs to make to reach the content they need.

For example, we have several topics for dashboard module types. Rather than have a parent topic that has only a brief introductory sentence and a list of links to each module topic, ensure that the parent topic itself has general information about the reports. In this example, it could be conceptual information about dashboards and modules, or even procedural information if configuration for each module type is similar.

Information typing

To help ensure a consistent user experience, make sure that you structure topics according per the information typing model, described in Information mapping.

Video

Create overview videos for all large-scale features, and for all other subject matter when showing would be more helpful to the user than telling. For example, you might create a video showing how to complete a task. You might create a video to provide conceptual information where motion in graphics would help the user grasp the concept.

As indicated by the previous examples, attempt to follow the information typing model when delivering content in videos. While a single video can contain several information types, try to separate those types. For example, you might begin with a brief discussion of the concept, followed by a task.

Strive to keep videos brief (under 2 minutes) and focused. A series of short task videos is often better than 1 long video for an entire process. Concept videos might be longer than task videos, but remember to keep them focused on the important information users need.

Embed videos in topics containing the same subject matter, as well as in the video library.

For detailed information about creating videos with Camtasia, see Working with videos.

Context-sensitive help

Context-sensitive help (sometimes referred to as bubble help or tool tips) is user assistance built directly in the UI to provide information about specific visual objects in the UI, usually configuration parameters. Users either mouse-over or click an information icon next to a UI object, opening a box/bubble containing information about that object. For example, the following image shows context-sensitive help for the Roles That Can Se This Report property.

The information should be very brief, but with enough explanation to help the user understand what do do with that UI object. Context-sensitive help should be written to assist the user with tasks. Always consider the task the user is attempting to accomplish in that UI, and provide context-sensitive help targeted to meet that need.

Not all UI objects should have context-sensitive help, since that would clutter the UI. As you test functionality during development, use your experiences as a user as well as knowledge from your Product and Design teams to help determine which UI objects (if any) need further explanation to help the user complete tasks in the UI. This effort should be collaborative, but feel free to initiate a discussion about context-sensitive help if one has not already been kicked off by your team.

Some teams teams might allow you to enter context-sensitive help text directly in the code. Other teams might want to limit access to code. In either case, be sure that your team uses Jira stories to track context-sensitive help development, and make sure you are part of that process.

UI inline text

Inline text is similar to context-sensitive help, but it is always visible in the UI. Use inline text to provide information that is critical enough or confusing enough that the user is unlikely to have success without it. Inline text must be used very sparingly, and when it is used it must be exceedingly brief. Usually, inline text is best used to help with a general function or feature instead of a specific property.

For example, the following image shows inline text that helps the user understand the impact of configuring preset filters at the report level:

Most often, the need for inline text is determined by the Design and Product teams, and is implemented by the Development team. However, your experience as a product tester and user advocate should empower you to suggest changes that might help users.

UI placeholder text

Placeholder text is sample text that appears in UI properties/fields, helping the user understand what to enter or do. When the user enters data or makes a selection, the placeholder text is replaced. For example, the following images shows placeholder text for the Data View property, followed by how the property looks after the user makes a selection:

A common example in UI design is to list formatting requirements to prevent users from encountering an error. For example, if a property disallows certain special characters, the user benefits from knowing that before trying to enter invalid data.

As with inline text, the need for placeholder text is determined by the Design and Product teams, and is implemented by the Development team. Consider your experience as a product tester and user advocate, and suggest changes.

Guided walkthrough

A guided walkthrough is a UI-housed step-by-step guide through a product UI or common task. Guided walkthroughs are educational in nature, as opposed to task-based. For example we might have a guided walkthrough to help users understand report-creation basics. The Development team might also develop a fully-functional wizard to help users complete report-creation tasks.

Guided walkthroughs should be:

• Short — The user is trying to complete tasks. Keep the walkthrough brief to help the user understand what is needed so he or she can get back to work.
• Focused — Keep it simple. If needed, consider a pool of related walkthroughs so users have more control over the scope of the help they receive.
• Interactive — Allow users to control when to progress to the next step, or even go backward to the previous step. Allow the user to quit a walkthrough at any time. (This requirement will be met by the walkthrough design process, which is ongoing.)
• Optional — Provide a way for users to start a walkthrough. (This requirement will be met by the walkthrough design process, which is ongoing.)

During the first few implementations of guided walkthroughs, use them to give users a tour of each Admin Suite tool UI. For example, we should eventually have walkthrough tours for the Navigation screen, Admin Suite Reports main screen, Admin Suite Surveys main screen, and so on.

Work with your Product team to determine where guided walkthroughs would have the most user impact. With these identified, work with your Development team to obtain access to the area of code where you can create the walkthrough steps and text for those steps. In the final step, include a link to a page in the main Product Documentation where the user can find more information.

Other ideas

Here are additional, still unexplored ideas for how we might deliver documentation. As we explore new ideas we will define guidelines for their style and usage.

• Interactive graphic
• Tutorial
• Interactive quiz