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.
