5

For the 'who is this application for' section of an application user guide, I have the following alternatives, I'm not happy with either one. How can I convey both elements more clearly and consisely?

What I want to convey:

  1. The business functions related to the specific metric ==> who in the sense of who might have to deal with the issue
  2. Why they would care ==> The specific issue the the application is meant to resolve

Current:

The intended audience is anyone tasked to ensure the accuracy of [analytic metric] generated by the their implementation of the [Specific Analytic Software] Platform, whether for [business function A], [business function B], [business function C], or [business function D].

Proposed:

The intended audience includes personnel tasked with ensuring the accuracy of [analytic metric] sourced from the [Specific Analytic Software] Platform. This information could be included within any of the following: [business function A], [business function B], [business function C], or [business function D].

Update

Based on your proposed solutions, here is my current, much improved take:

This application is for anyone in [business function A], [business function B], [business function C], or [business function D] who compiles [analytic metric] using (ESP). It is designed to help you ensure the accuracy of the [analytic metric] by connecting to ESP to generate and collect, in just a few minutes, related analytic and underlying data that would otherwise take hours to compile. The compiled information is then organised and presented in a way that makes troubleshooting and documenting specific [analytic metric] values easier.

Comments?

Improve this question
  • Hi and welcome! A couple questions to help me understand what you're going for: it sounds like the reader has an application that was in turn built by your product (so 2 steps removed); is that right? Is this an exhaustive list of relevant business functions or are these examples? When you say "the information could be included", what information do you mean -- reports? Thanks! – Monica Cellio Feb 13 '13 at 21:37
  • The reader has a very complex enterprise software product (ESP) that generates many analytic metric values. My product connects to the ESP (via API) to generate, collate and intelligently present the particular metric in question together with related supporting data allowing the user to troubleshoot questionable results or to document those specific results for recordkeeping/reporting purposes. Doing the same task using the ESP GUI manually would take hours to do what my product does in minutes. – marfarma Feb 13 '13 at 22:09
  • Your rewrite is much better. "Intended audience" probably should be reserved for a heading or index entry. The second sentence has me buggy because it's almost right. Maybe: When connected to ESP, [application] will automatically generate and collect analytic and underlying data related to [analytic metric] that would otherwise take hours to (manually?) compile. (I didn't like the extra clause - in just a few minutes, but "automatically" might not be accurate.) – Joe Feb 20 '13 at 23:43
  • "Automatically" continued: The point is to put something directly in the sentence that doesn't require a comma separated phrase which makes it "feel" difficult or complicated. – Joe Feb 20 '13 at 23:52
2

Try something like this:

This application is for users of (ESP) who need to understand its results quickly and easily. (Product) takes the metrics compiled by (ESP) and presents them in a way that makes troubleshooting and documentation easier. (Product) produces reports for (business function A), (business function B), ... .

Rationale:

First, explain how it fits in with the context they already know. Then tell them how your product fits into that world; they (presumably) know the pain of dealing with (ESP), but they've never heard of you. Focus on what your product does for them, rather than who they are; if you say, for example, that a product is for users of type X, then users of type Y who also need to do that thing may not realize you can help them. But everybody has some idea of the problem he's trying to solve. (Well, usually. We hope. :-) )

Depending on your house style, you might want to list the business functions your product addresses in a bulleted list instead of in running text like above. This helps people who are skimming. Think about the last set of product specs you read (online, on a physical package, or whatever); it was probably a list, wasn't it? It was designed to make you quickly realize "I need this"; so too is this section of your document.

Improve this answer
1

[The application] is designed with [business function A], [business function B], [business function C], and [business function D] in mind, with the specific purpose of ensuring accuracy of [analytic metric] generated by your implementation of the [Specific Analytic Software].

As I understood, some unfortunate code monkey gets tasked with debugging a huge enterprise software product using your tool as aid in understanding what happens under the hood of that ESP. That would mean the actual intended audience is the overlords of that code monkey.

Putting it in more PC terms, the intended audience is the businesses which perform functions [A,B,C,D] and the actual use/purpose is ensuring the accuracy.

The fact this purpose is achieved by harnessing said monkey to your tool and letting them loose on the ESP, is out of focus of the the business-side, an insignificant detail left for the technical crew which won't be interested in that section of the document anyway.

Improve this answer
  • Substitute "quant monkey" for "code monkey." And it's more data mining for "garbage in" when a whiff of "garbage out" is detected than debugging the ESP. But the difference is immaterial. As you say, the intended audience consists of the businesses and the actual use/purpose is ensuring the accuracy. – marfarma Feb 14 '13 at 18:00
  • As I'm sure has been discussed on Writers Meta, it's hard to pick the 'right answer' in this context. I ended up blending aspects of both your and @monica-cello 's answers - but I could only pick one. – marfarma Feb 15 '13 at 15:43
1

For everyone who wants to control the accuracy of [analytic metric] of their [Specific Analytic Software] Platform implementation. No matter if it is for [business function A], [business function B], [business function C], or [business function D].

Your examples are exactly in that formal tone that makes me fall asleep. Some guides are forced to be written in that tone, because of bosses who have no single clue about user guides (or especially users). I hope you do not have to suffer one of these.

I wouldn't use adjectives (or derived adverbs) like "quick" and "easy". Always I read stuff like this I think automatically "Oh, what a splendid idea. I always try to make my programs slow and hard to comprehend". (Add sarcasm tags at will.)

Improve this answer
  • 1
    Indeed. Being troubled by the soporific qualities of either option was the principal motivation for posting this question. – marfarma Feb 14 '13 at 18:20

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.