Puzzling it out: Piecing together topics to create scenario-based documentation NetApp Information

Engineering

1

2

Overview

2

Business/Project Need Scenario-based Pilot Objective Process: Planning and Developing

Workflows Technical: Implementing the Markup

Solution

Business/Project Need Two important factors drove the business/project need:

1. Usability Explain how a customer would use a complex collection of

products to complete a particular goal such as backing up virtual machines.

2. Supportability Reduce customer calls and escalations once the product is

deployed and widely used by our customers.

Information Engineering was tasked with creating a documentation strategy that would satisfy these needs.

3

Scenarios & Workflows The Technical Publications industry defines these concepts similarly:

– Sequence of task topics that a customer can use to achieve an overall goal.

– Composed of a parent task topic with two or more subordinate child task topics. The parent introduces a process and any specific information needed to complete all subsequent tasks. The child topics describe each of the tasks to complete in the process.

– Includes detailed information, providing specific examples in both the parent and child topics, as if the reader were going to actually enter the information provided in those examples (such as IP addresses, names of resources, etc.)

Workflows are a more generic version of a scenario where the topic-level details are not presented. At NetApp, our preferred method of writing is workflow-based.

4

5

Scenario-based Pilot

First release of end-to-end goal-oriented documentation Based on product management input Product management and development engineers as SMEs Included very specific information about a particular situation Maintenance nightmare for IE (tech pubs) team Lack of topic reuse because of specificity in content Global Support indicated it had little use after first read

Wasn’t a good "bang for the buck", given overall effort involved

6

Example Scenario

6

Example: Introductory Information in Original Workflow Topics Create the resource pools

Organize the London storage system hosts into a resource pool for backups and the Minneapolis storage system hosts into a resource pool for mirror copies. The NetApp Management Console data protection capability can provision storage out of these resource pools, as needed.

Before you begin

Ideally, hosts in a resource pool are interchangeable in terms of their acceptability as destinations for backups or mirror copies. When developing the protection strategy for the seismic test data, you identified London and Minneapolis hosts with similar performance and quality of service levels that would be suitable members of the same resource pool.

You have already created aggregates of unused space on hosts you intend to assign to resource pools. This ensures that there is adequate space to contain the mirror copies and backups.

Before creating the resource pool, you need to gather the information necessary to complete the Add Resource Pool wizard:

• The name of each resource pool to be created • The time zone that the policy schedules should assume when timing protection events

Since an administrator might be in a different time zone than the resource pool, it is important to be clear about which time zone applies to schedules.

• The physical resources to be included in the resource pool (cont.)

Specific environment & configuration

7

Example Scenario (cont.)

7

Steps 1. From the menu bar, click Data > Resource Pools.

The Resource Pools window appears.

2. Click Add. The Add Resource Pool wizard starts.

3. Complete the steps in the wizard to create the London Backup resource pool. Use the following settings: • General properties

Name: London Backup • Physical resources

Group: Global Resource type: Hosts Select the storage systems that you previously verified have good credentials and have SnapVault Secondary and SnapMirror licenses enabled.

4. …

Result The London Backup and Minneapolis Mirror resource pools can be viewed in the Resource Pools list.

After you finish You next evaluate and modify the protection schedules

Specified names, selections, etc.

This info had to be verified & potentially updated every time the UI changed.

8

Retreat or Regroup?

8

Users liked the idea of what we were trying to do, but didn’t find the implementation as useful as everyone had hoped.

Decisions: – Retain the basic concept of a scenario-based guide – Involve Global Support – Simplify and genericise the scenarios into workflows

9

Objective

What we wanted to achieve with workflows – Provide user with cross-application/multiple user interface

goal-oriented tasks (all applications part of same product, but each had its own user interface)

– Fulfill field personnel request for workflows – Create generic content to lower maintenance cost and

re-use topics – Provide frequently used (common) workflows; not a

comprehensive set of workflows for entire product

10

Designing and Developing Workflows

10

1. Identify stakeholders 2. Identify and prioritize workflows 3. Identify subject matter experts 4. Gather information 5. Create content 6. Review, validate, and modify

11

Identify Stakeholders

11

High-level stakeholders were needed to identify and prioritize the workflows

Challenge Resolution Required getting product managers, product architects, global support, and other busy people together at the same time across time zones, across project schedules.

• Escalated this issue to a director to get people to schedule time to participate.

• Scheduled mandatory meetings that were highly organized and focused to fully utilize stakeholder’s time.

12

Identify and Prioritize Workflows

12

Stakeholders needed to identify frequently used workflows

Challenges Resolution Stakeholders had their own perspective and business needs. For example, Global Services focused on customer escalations, while Product Management focused on promoting new features.

• Multiple meetings were needed to identify all of the workflows.

• We restricted the number of workflows to be documented for the release to 10.

Stakeholders were frequently distracted by UI issues.

Meetings were structured and focused to stay on task.

13

Identify Workflow SMEs

13

Needed subject matter experts who understood the entire workflow, including interaction between applications.

Challenges Solutions Developers were in the middle of developing the product in a tight schedule. Support personnel could be called away at any time to respond to customer escalations.

We frequently had to ask managers to assist in freeing up people’s time.

14

Gather Information

14

Interview SMEs

Challenge Solutions Often SME did not understand how different applications worked together, so had difficulty identifying the flow of the workflow.

• SMEs needed to research the workflow tasks and application interactions.

• Pulled in higher-level SMEs (product architects, etc.).

Product was brand new and UI and functionality weren’t fully cooked; we were documenting a moving target.

Scheduled time for revalidation shortly before release.

15 15

Gather Information

15

Create content

Challenges Solutions Writing was more complicated and required greater effort than anticipated. - Application interaction needed more explanation.

• Estimate for writing effort was increased.

• Effort became easier as we developed additional workflows.

Identified gaps in documentation. Created topics to fill in these gaps. (This had the side benefit of improving our other task-documentation.)

Introductory and "tie-in" text was more extensive than expected.

• Provided alternative short descriptions to make them more relevant to the workflows.

• Provided alternative topic titles as "steps" in parent.

• Added prerequisites, content, and postrequisites (assumptions, etc.) in the parent topic.

Review, Validate, and Modify

16

Workflows needed to be reviewed and validated

Challenges Solutions Required developers and Global Support to review documentation.

Performed unit reviews of workflows and incorporated feedback into subsequent workflows.

Required QA to validate workflows. Requested a dedicated QA developer to validate all workflows, including a final pass.

All stakeholders reviewed document. Had stakeholders commit to reviewing document at beginning of project. Asked stakeholders to review workflows when we had several to review at once.

Example Parent Topic

17

Implementing the Technical Solution

How did we implement the workflows? Challenges & solutions Technical implementations & examples

Will focus on what the writers had to do with the DITA markup.

– Will mention in passing other issues you might find of interest.

18

Technical & Architectural Challenges & Solutions

19

Challenges Solutions How do we reduce maintenance and maximize topic reuse?

Restructure the workflows to be more generic. Only parent topic contains specific content.

How do we protect the integrity of our topics with multiple writers accessing topics from multiple projects?

Use the CMS.

CMS was new to writers. Took that into account in the schedule and planning.

The parent topic didn’t transform the way we wanted it to.

Had to research technical changes required. Had to modify our transform.

20

Technical & Architectural Challenges & Solutions (cont.)

20

Challenges Solutions Part of the new design impacted department standards.

Had to get approval from our architecture committee.

Some of the writing style impacted our style guide.

Had to get approval from our editorial committee.

Required effort from the tools team, which was already very busy.

• Writer did initial investigation. • Got the work prioritized with our tech

pubs tools team based on project schedule and need.

Required writers to modify markup in the DITA map in new ways.

Had to research and do test implementations to get it right, document it, and train writers.

What Did the Writers Have to Do?

Create a map Create a new parent topic Add parent & child topics to the map Modify DITA markup in the map

Examples will focus on modifications to the DITA markup; other work is basic writer effort.

21

22

Original Transformed Results for PDF

22

Backing up physical storage objects To back up your physical storage objects, you must create a new dataset and then assign an existing protection policy and weekly backup schedule to the dataset.

Adding a dataset of physical storage objects

Assigning or changing a protection policy

• No section titles

• No step numbers

• Link text for steps pulled from child topics

• Step link preview text was missing

23

Result We Wanted

Backing up physical storage objects To back up your physical storage objects, you must create a new dataset and then assign an existing protection policy and weekly backup schedule to the dataset.

Steps 1. Add a dataset of physical storage objects.

Creating a new dataset enables you to group and manage physical storage objects that share the same protection requirements.

2. Assign or change a protection policy. Assigning a protection policy to your new dataset enables you to specify how you want your data to be protected, including the protection topology, the backup schedule, and backup retention length.

23

• Section titles

• Step numbers

• Link text (steps) in imperative

• Link preview text with relevant information

24

The New Design: Example

Parent workflow topic with "steps"

Child task topic

Navigation: Parent & child topic titles

Also used for TOC entry

Sample PDF output of our current workflow structure.

25

How Did We Get the Result We Wanted?

Tools team: Verified that DITA elements worked as needed and made modifications as required – Standard DITA usage; no customization required

Writers: Added markup in the DITA map – <topicref … collection-type="sequence">

Adds step numbering to the child topic title links. – <topicref … outputclass="workflow">

Pulls the child topic short description as link preview text for steps in the parent.

– <linktext> Overrides the text in the steps (link text) of the parent.

– <shortdesc> Overrides the link preview text in the steps of the parent.

26

Markup for Adding Step Numbers

26

To create a parent task topic containing an ordered sequence of links to child subtasks, in the workflow map add collection-type="sequence" within the <topicref> element. Example: <topicref href="parent-topic-GUID" navtitle="parent-topic-title" collection-type="sequence" <topicref href="child-topic-1-GUID" navtitle="child-topic-1-title" /> <topicref href="child-topic-2-GUID" navtitle="child-topic-2-title" /> </topicref>

27

Adding Step Numbers Transform Result

Backing up physical storage objects To back up your physical storage objects, you must create a new dataset and then assign an existing protection policy and weekly backup schedule to the dataset.

Steps 1. Adding a dataset of physical storage objects

2. Assigning or changing a protection policy

27

collection-type ="sequence"

Step numbering

28 28

Markup for Including Preview Text in PDF Output for Workflows

The default PDF output does not display the link preview text for each step in the parent topic. We wanted link previews to show up in PDF for workflows but not in other PDF output types. To get this behavior, in the workflow map we had to add an outputclass to the <topicref> for the parent topic. Example: <topicref href="GUID" navtitle="Backing up physical storage objects" collection-type="sequence" outputclass="workflow" type="task"> </topicref>

29

Link Preview Text Transform Result

Backing up physical storage objects To back up your physical storage objects, you must create a new dataset and then assign an existing protection policy and weekly backup schedule to the dataset.

Steps 1. Adding a dataset of physical storage objects

You can include physical storage objects in a dataset so that you can manage the protection and provisioning requirements of those objects as a group..

2. Assigning or changing a protection policy You can assign a policy to a dataset to specify how the data is to be protected.

29

outputclass=workflow

Link preview text pulled from child topic short descriptions

30

Overriding Text in Parent Topic Steps

We used overrides to change the text that displays in the steps and in the step link preview text in the parent topic.

Overrides are implemented at the map level. You can incorporate <linktext>, <shortdesc>, or both

overrides in the same workflow. Tip: You might override the title to put it in the imperative; you might override the short description to provide information more specific to your workflow than the standard short description can provide.

31

Markup for Title Override

To override the child topic’s title that is displayed as a step in the workflow parent topic, add <topicmeta><linktext>custom step text for parent topic</linktext> </topicmeta> before the </topicref> element. Example: <topicref><topicmeta> <linktext> Add a dataset of physical storage objects. </linktext> </topicmeta> </topicref>

Note: This markup does not change the title in the target task (child topic), it only changes the text in the "steps" of the parent topic.

32 32

Title Override Transform Results

Backing up physical storage objects To back up your physical storage objects, you must create a new dataset and then assign an existing protection policy and weekly backup schedule to the dataset..

Steps 1. Add a dataset of physical storage objects.

You can include physical storage objects in a dataset so that you can manage the protection and provisioning requirements of those objects as a group.

2. Assign or change a protection policy. You can assign a policy to a dataset to specify how the data is to be protected.

32

Title overrides

<linktext>

33

Markup for Short Description Override

To override the child topic’s short description that is displayed in the parent topic, add <topicmeta><shortdesc>custom description for parent topic</shortdesc> </topicmeta> before the </topicref> element.

Example: <topicref><topicmeta> <shortdesc> Creating a new dataset enables you to group and manage physical storage objects that share the same protection requirements.</shortdesc> </topicmeta></topicref> Note: This markup does not change the short description in the target task (child topic), it only changes the text in the "steps" of the parent topic.

34 34

Short Description Override Transform Result

Backing up physical storage objects To back up your physical storage objects, you must create a new dataset and then assign an existing protection policy and weekly backup schedule to the dataset..

Steps 1. Add a dataset of physical storage objects.

Creating a new dataset enables you to group and manage physical storage objects that share the same protection requirements.

2. Assign or change a protection policy. Assigning a protection policy to your new dataset enables you to specify how you want your data to be protected, including the protection topology, the backup schedule, and backup retention length.

34

Short description (link preview text) overrides

<shortdesc>

35

Example of Combined Markup in the Map

In this example, the navtitle contains the original title of the topic.

<linktext> contains the text that will display in the workflow instead of the original title. <topicref navtitle="Backing up physical storage objects" href="GUID" collection-type="sequence" outputclass="workflow" type="task">

<topicref navtitle="Adding a dataset of physical storage objects" href="GUID"> <topicmeta> <linktext> Add a dataset of physical storage objects </linktext> <shortdesc>Creating a new dataset enables you to group and manage physical storage objects that share the same protection requirements.</shortdesc> </topicmeta></topicref>

<topicref navtitle="Assigning or changing a protection policy" href="GUID"> <topicmeta> <linktext> Assign or change a protection policy.</linktext> <shortdesc>Assigning a protection policy to your new dataset enables you to specify how you want your data to be protected, including the protection topology, the backup schedule, and backup retention length.</shortdesc> </topicmeta></topicref> </topicref>

Best Practice Suggestions

Have each workflow in a separate map – Easier to track workflow topics – Easier for writers to keep track of topics they’re

working on – Easier to reuse complete "package"

36

Best Practice Suggestions (cont.)

Add a comment in the parent topic – State that the parent is part of a workflow.

Makes it clear that this is not a stand-alone topic.

– Include the map GUID associated with the workflow. Makes it easier for anyone else who might want to use the workflow.

37

38 38

Contact Info

If you have questions, you can contact us at: Mitra.Mohsensian@netapp.com Rita.McKissick@netapp.com Beverley.Andalora@netapp.com

39

40