Describing software user interfaces using DITA

Mon Sep 14 05:00:56 PDT 2009

Are you going to be at the tekom conference in Germany this November? If so,
I'd love to take some time to talk about this one. However, as general
statements, consider what users want to do, not the name of a dialog. The
indeas such as prinint and approving or reviewing reports are a great start.
However, what also becomes hugely important is to consider the audience and
to organize information groups (maps) based on both the type of content you
need, but also the audience in regards to their skills.

If you figure out the topic level (not the specific element level) ideas of
what the audience is, then it will help to determine what you should
document and how deeply. You can, for example, decide that audience has
administrator as it's primary target. The admin could be responsible for
customizing. The experience level is general. So, for <audience
type="administrator" job="customizing" experience="general"> you can decide
that the topics you include are more advanced. You assume they can print,
heck, you may assume they can format c: and reinstall the OS if they are an
"average level" administrator in the IT world. So, what can a user at that
background do with your product?

Perhaps user surveys. Ask people "what is your job title and what are your
skills" and then use that to recover information on the audience that you
can then use to decide on the tasks and the depth of detail.

So, before anything, identify what "users" means in the context of your
questions. Once you have ID'd who you are writing for, the type of content
you write, and the depth of information may be easier to understand.

So, based on that idea, I'll try the three questions. You ask where to
describe the very simple tasks and I'd say you don't. *IF* your audience is
at a level of skill that already can perform the simple tasks. Or build
those tasks into a tutorial. Put together a tutorial on how to open a
report, then how to review the report, and finally how to write a rejection
comment. That covers two of the tasks in a single tutorial AND it lets the
user do something. Heck, most of us can learn a lot by reading a well
written tutorial.

Where do you describe task-related connections between features is another
question. If I understand that correctly, you want to know where you would
put together the link for Reviewing/Approving. In a relationship table
<reltable> (used by the maps) you can put a relationship between the two of
these. Try to never put the links <xref> between your topics INSIDE the
topics. Otherwise the famous "unresolved xref" idea could happen if you
don't include required files. Just create the map and use the reltable as
much as you can to drive the connections between the topics you write for
the features.

As for reference information, same idea. Put the links between
topic/concept/reference/task into the map using the relationship table when
you can. It's not something that is 100% the "right answer" but it will make
a big difference in how you manage the links. By removing them from topics
you reduce the likelyhood that one topic needs three others (which in turn
each need 2, 3, 4 or however many more) and growing your single and simple
set of three or four topics into a deliverable that needs 23 topics to
print.

So, know your audience, and ID them early. Learn what they will actually
want and use. What are their goals? When will they likely have questions
that trigger help and what do they know before doing so. Once they know all
this, can they quickly find it because it's well detailed? And for links,
use the maps and the reltables.

Hopefully this is a bit of help. Let me know if there are more questions.
Again, if you are at tekom, great. I'll hope you stop by and say hello. For
anyone that is in North America, take the time to consider www.lavacon.org
as well since I'll be there, as will others who are part of this forum and a
few of the people behind DITA, the toolkit, and the tools that work with the
architecture.

Best of luck,

Bernard

Bernard Aschwanden
President
Publishing Smarter

www.publishingsmarter.com 

-----Original Message-----
I am looking at my software user interface and evaulating what should be
tasks, comcepts and reference. Right now I am creating context-sensitive
help and a paper manual (single-sourced).

In my interface I can create hundreds of tasks, but they are very simple
almost self-explanatory on screen.
Tasks like 

"Printing a report",
"Approving a result",
"Reviewing a result"
"Writing a reject comment"

What is more difficult is to describe what happens behind the scene.
What new features opens up for you depending on your choices.

Yet another issue is that what is probably the most difficult for users to
understand is typical reference information like all the symbols on
different screens. They are not all intuitive and without documentation the
user hasn't a clue to what is going on. 

Questions:

Do you describe the very simple tasks? If so, how do you handle hundreds of
small tasks in a paper manual?
Where do you describe task-related connections between features?
Where do you place reference information that is necessary for the user to
know?

Are there any good examples of DITA doumentation that illustrate my issues?

Best regards,

Verner
--------------------------------------------------------

Radiometer Medical ApS
Akandevej 21
2700 Bronshoj
Denmark
Phone: +45 38 27 38 27
CVR: 27 50 91 85
www.radiometer.com
For the latest trends in acute care testing, go to Radiometer's knowledge
site www.acutecaretesting.org

--------------------------------------------------------

Please be advised that this email may contain confidential information.
 If you are not the intended recipient, please do not read, copy or
re-transmit this email.  If you have received this email in error, please
notify us by email by replying to the sender and by telephone (call us
collect at +1 202-828-0850) and delete this message and any attachments.
Thank you in advance for your cooperation and assistance.

In addition, Danaher and its subsidiaries disclaim that the content of this
email constitutes an offer to enter into, or the acceptance of, any contract
or agreement or any amendment thereto; provided that the foregoing
disclaimer does not invalidate the binding effect of any digital or other
electronic reproduction of a manual signature that is included in any
attachment to this email.
_______________________________________________

You are currently subscribed to Framers as bernard at publishingsmarter.com.

Send list messages to framers at lists.frameusers.com.

To unsubscribe send a blank email to 
framers-unsubscribe at lists.frameusers.com
or visit
http://lists.frameusers.com/mailman/options/framers/bernard%40publishingsmar
ter.com

Send administrative questions to listadmin at frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.