Replies to This Discussion

Permalink Reply by Richard S. on January 9, 2012 at 1:40pm

I'm not sure there's a single choice that works best in all cases. I use different approaches depending on context and type of document.

The one you describe (when we need a reader to think about their own product names in the context of a task) is a tricky one. We've tried and tested a variety of different approaches, and none works particularly well. :-(   We also have the interesting challenge that our docs are in English, but serve a predominantly non-native English speaking audience.

Here's an example from a particular case where we needed our readers to create and submit electronic serial numbers for their products. The numeric sequence had to embed something specific about the model group, and the form submission had to identity brand, OEM, ODM, and model number. Seems simple, but we were constantly getting the submissions done wrong. Over time, we observed: 

• The real company approach works best. I suspect this is because when you use a real company name, they all know they need to change it. Unfortunately, they all seem to get a annoyed (enough to tell us about it) when it's a competing company that's listed. Though we aren't legally prevented from doing this, we've been asked (and agreed) not to. 
• The fake company was second best, but it confuses a fair number of folks. You have to come up with something "real sounding" but still fake enough that the intent is obvious. As often as not, people would submit forms and copy the fake company name verbatim as if it were their own.   
• For our audience, the not having an example was the worst of the 3. This yielded the highest rate of improper submissions. 

For examples in tasks that don't involve company or product names, this problem gets a lot simpler. In these cases, we tend to use the imperative and give a reasonable number of typical examples. Something like:

You must implement getLanguage() to return a string consisting of one or more valid BCP-47 language subtags. For example:

• en
• en-US
• en-AU
• fr-CA
• pt-BR
• Brai  

• ▶ Reply

Permalink Reply by Mark Baker on January 9, 2012 at 2:34pm

Couldn't you just put a validation rule on the company name field that detect if it contains your fake company name and warn the user to fix it before submitting the form? Mechanical error detection generally beats any amount of instructional error prevention.

• ▶ Reply

Permalink Reply by Richard S. on January 9, 2012 at 5:08pm

For the web form submission, we actually did that, then subsequently improved the workflow to remove this need altogether. But the web form was only half of the submission, there was still an issue with the data itself (which was encrypted data). Having the server decrypt the data for the sake of validating it during form submission would have opened some security holes we weren't willing to open. Building and deploying such a system securely wouldn't have been worth it at the time (a ten dollar solution to a ten cent problem). 

• ▶ Reply

Permalink Reply by Chastin Howerton on January 19, 2012 at 3:25pm

Hi, Ann. I work for a small software company, and we actually use a combination of all three:

Using Client Data - When doing product demonstrations during the implementation process, we use the client's real data so they can relate to the task in the demo. When we are training clients, we allow them to input and work with their own data rather than dummy data that way even though their software is new, the content they're working with is still familiar.

Using Test Data - When drafting content for our manuals, quick start guides, and How To's, we use fake data in our screen shots to avoid issues with displaying client information.

You Statements - When we send out release notes to clients, we try to direct examples to our users: "If you want to add a new line to your table, click the green plus sign next to "Add a New Line."

• ▶ Reply

Permalink Reply by Milan Davidović on January 19, 2012 at 4:58pm

When I worked on medical device labelling (which, in industry parlance, includes manuals), our legal department had concerns over what appeared in scenarios and screen shots. You may wish to consult your own legal folks at some point to see what their concerns are, if any.

• ▶ Reply

Permalink Reply by Daniel Archer on February 21, 2012 at 2:25pm

We have a variety of web-based software applications for government clients that in the production environment have a lot of sensitive personal information. We're not allowed to show any of that in the scenarios we develop for user manuals and help sets.

The best way around that is to have the developers implement realistic sample data. One way we do this is have them run a script to populate the database in the test environment with data from the US census, but thoroughly scrambled so none of it matches. SSN's would typically be generated as random 9 digit sequences, since they are the most sensitive piece of information. There are several different techniques that the devs can use to obfuscate data so that it retains authenticity for scenarios.

Another issue we run into is that we often work out of a QA environment where the UI is focused on a case workflow. Unit testers (devs), functional testers (BAs), and regression testers (QA) like to populate these cases with the likes of Bilbo Baggins and Optimus Prime (it all comes back to sci fi, Monty Python, and LoTR). I can't put those in a published scenario, so I either have to create my own test data and keep it clean, or ask the developers to look into running scripts that create cases with randomized data. If I'm creating my own test data, I usually have to track down a SME to make sure that my imaginary case has some semblance of authenticity.

The other technique I resort to is to use SnagIt to work around ugly data. I only do this if I don't have time (or enough clout) to get better data, and usually only for a handful of screenshots. Cleaning up images is pretty tedious work, and obviously isn't an option for videos.

At the end of the day, if the Marines stationed in Okinawa or the medical evaluators evaluating a wounded warrior's case can't look at my scenario and see how it relates to their tasks, the UM or help set loses a lot of value. I think it's more important that the data ring true to life than that it match their individualized task flow.

• ▶ Reply

Permalink Reply by Daniel Archer on February 21, 2012 at 2:33pm

After reading a different discussion, I'm reminded of the value of a development team that values defined personas, use cases, or user stories. A good BA will do 98% of that work for you, and if management is paying attention, the whole project will be thinking in those terms. In that case, most of your scenario work is already done for you - you can create additional scenarios within the existing framework.

• ▶ Reply