IBM Presentations: Blue Pearl Basic template

Download Report

Transcript IBM Presentations: Blue Pearl Basic template

IBM User Technologies

Authoring DITA content

IBM User Technologies Overview      

Topics Making topics retrievable Identifying the topics you need Authoring tasks Authoring concepts Authoring reference topics

2 Authoring with DITA XML

IBM User Technologies Topics 

Definition



Structure



Example

3 Authoring with DITA XML

IBM User Technologies Topic – expanded definition 

A topic is an independent unit of information.



It is meaningful when it is displayed alone.



It follows the rules for a specific information type.

4 Authoring with DITA XML

IBM User Technologies Structure of a topic    

Heading Text May contain nontext elements such as tables or graphics In a Web, probably contains links to other closely related topics

5 Authoring with DITA XML

Topic structure IBM User Technologies

6 Authoring with DITA XML

IBM User Technologies Demonstration: authoring a simple topic

7 Authoring with DITA XML

IBM User Technologies Topic retrieval 

Navigation in print



Online retrieval problems

8 Authoring with DITA XML

IBM User Technologies Navigation aids in books The table of contents and the index are the state of the art in print navigation. These systems have been refined over centuries of use. They are common because they work.

Many of the standard approaches to improving online information originated in design for books: topic orientation, task orientation, Minimalism, chunking, information typing….

9 Authoring with DITA XML

IBM User Technologies Retrievability problems online 

Jared Spool has found that on the

best

sites, users cannot find what they are looking for 57% of the time.



On-site search engines fail 70% of the time.

10 Authoring with DITA XML

IBM User Technologies Improving online navigation       

Logical chunking Guidelines Navigation tree/table of contents Topic headings Related links Index Search

11 Authoring with DITA XML

IBM User Technologies Chunking  Explain one thing at a time – easier for audience to integrate learning and doing  In a concept topic, address only one idea or one component.

 In a task topic, explain how to do only one task.

 In a reference topic, explain only one command, language element, or API.

12 Authoring with DITA XML

IBM User Technologies Guidelines  When multiple writers contribute to a single solution (infocenter, book, helpset…) you need guidelines to ensure content can be integrated into a usable solution  Guidelines are part of the picture: DITA for technical ability to integrate Guidelines for consistency of result Usability tests and customer feedback for quality of result © 2005 IBM Corporation

13 Authoring with DITA XML

IBM User Technologies Navigation/table of contents  Use task-based organization for most important content – what does the user want to do?

 Use system-based or category-based organization for reference content – what can the product/system do?

 Organize not just for retrieval, but for learning: users need to understand how tasks and systems fit together – if they know what they’re looking for, they’re probably using search, not the table of contents © 2005 IBM Corporation

14 Authoring with DITA XML

IBM User Technologies Topic headings -- questions  Does your heading tell users exactly what information the topic contains?  Does it differentiate this topic from other topics in the information center?

15 Authoring with DITA XML

IBM User Technologies Topic headings – general tips  Compose titles that are meaningful to users.

 Control vocabulary to aid searching and browsing.

16 Authoring with DITA XML

IBM User Technologies Topic headings – specific tips  Put keywords at the beginning of the title so that users can quickly identify the most important aspect of the information that the topic contains.

 The structure of the topic title should let people know whether they can expect task, concept, reference, tutorial, or sample information.

17 Authoring with DITA XML

IBM User Technologies Topic headings -- summary

Tasks Start the title with a present participle (verb with an -ing ending) Avoid “Using” and Working with”.

Concepts Reference Samples and tutorials Use a noun phrase.

For topics about commands, language statements, configuration parameters, and so on, begin the topic title with the command or keyword, followed by the descriptive name of the technical entity

db2sync - Start DB2 Synchronizer Command

Start with the name of the information type. Provide a descriptive name for the sample or tutorial that starts with a present participle.

Authoring with DITA XML

19 Authoring with DITA XML

IBM User Technologies Linking principles  Linking should complement the navigation hierarchy.

 Leave a

scent

to give users confidence that they can find what they need.

20 Authoring with DITA XML

IBM User Technologies Spool on linking  Jared Spool has done usability tests that show that embedding links (surrounding them with text) reduces users' success in finding information.  Spool’s research indicates that longer links often work better than short ones.  He has found that people scan for

target words

(keywords).

21 Authoring with DITA XML

IBM User Technologies Demo: adding a link  xref  link  linklist  Linking to non-DITA topics  Linking to external topics  Linking to topics the build process can’t reach

22 Authoring with DITA XML

IBM User Technologies The danger of authoring links in topics  Create a dependency on the target, which reduces the reusability of the topic, and increases the chance of it breaking when the information set changes  Map-based links manage related links, and certain kinds of embedded links – reducing risk, increasing efficiency  More on maps later © 2005 IBM Corporation

23 Authoring with DITA XML

IBM User Technologies Indexing   

indexterm element Nesting indexterms Managing indexterms:

24 Authoring with DITA XML

IBM User Technologies Improving search information  Operating system  Type of information (concept, task, reference)  Component  Book  User role

25 Authoring with DITA XML

IBM User Technologies Improving search retrieval  Cram as many keywords onto the page as possible.

 Make introductory files short and use the most common keywords in them.  If tools permit, track the keywords employed by users searching your web.

26 Authoring with DITA XML

IBM User Technologies Identifying the topics you need       

Topic hierarchies Minimalism Reference topics: the safety net Task analysis Task orientation Completeness Prioritizing: demos and tutorials for key tasks

27 Authoring with DITA XML

IBM User Technologies Topic hierarchies  The topic hierarchy is the plan that writers follow in constructing a Web of information.  Task information is the core of every good documentation hierarchy.

 Concept topics provide the background information that users require to successfully attempt a solution or to use a product or component.

 Most reference topics can be grouped into a few broad categories (for example,

commands

language elements

28 Authoring with DITA XML

IBM User Technologies Minimalist principles  Allow learners to start immediately on meaningful tasks.  Minimize the amount of reading and other passive forms of training by allowing users to fill in the gaps themselves  Include error recognition and recovery activities in the instruction  Make all learning activities self-contained and independent of sequence.

29 Authoring with DITA XML

30 Authoring with DITA XML

IBM User Technologies Task analysis  Which tasks are most important to users?

 What sequence do users follow?

 Where do they encounter difficulties?

 What roles exist among the users?  What is the typical knowledge level of people in each of those roles?

 Who does which tasks?

31 Authoring with DITA XML

IBM User Technologies Task orientation  Describe the user’s tasks, not the product’s functions.

 Start with a list of major tasks.

 Break those tasks into smaller tasks and steps.

 Provide (or link to) background information (concepts).

 Point (or link) to related reference material.

32 Authoring with DITA XML

IBM User Technologies Completeness  Do we provide all the information needed to perform a task?

 How much should we document?

 How much detail should we provide?

 Should we repeat concept information in task topics or refer to it?

 Do we link to all the supporting information needed to perform the task?

33 Authoring with DITA XML

IBM User Technologies Prioritizing     Use reference documentation as the safety net Use task analysis for main user tasks Add conceptual information to support task flows Save learning information – tutorials, samples, demos - for key tasks © 2005 IBM Corporation

34 Authoring with DITA XML

IBM User Technologies Authoring task topics  Guidelines  Demonstration

35 Authoring with DITA XML

IBM User Technologies Task topics  Document the steps that a user follows to accomplish a goal.

 Begin the heading with a verb so users will recognize it as a task.  Use an opening paragraph to introduce the task and provide context for it.

36 Authoring with DITA XML

IBM User Technologies Task topics (continued)  Use a numbered list for the steps the reader must follow to complete the task.  Write the steps as brief imperative sentences. When the user's context has changed, introduce the step with a phrase that establishes that context (for example, In the Topics window, ...).  Write one step for each significant user action. © 2005 IBM Corporation

37 Authoring with DITA XML

IBM User Technologies Task topics (continued)  If a task has more than nine steps, try to divide it into two or more separate tasks.

 Document only one way of doing a task in each topic.  If the task is one of a set sequence of tasks, provide a link to the next task.

 Provide links to parent tasks and to closely related concept, task, and reference topics.

38 Authoring with DITA XML

IBM User Technologies Task structure

39 Authoring with DITA XML

IBM User Technologies Example  Authoring a task topic

40 Authoring with DITA XML

IBM User Technologies Authoring concept topics  Guidelines  Demonstration

41 Authoring with DITA XML

IBM User Technologies Concept topics  Document the background knowledge users need to successfully use the system, product, component, or feature. Concept topics should give the reader a mental model of how the system works.  Use a noun or noun phrase as the heading.  Use paragraphs to document concepts.

42 Authoring with DITA XML

IBM User Technologies Concept topics (continued)  When introducing a new term, begin with a definition; then, expand that definition.

 Add diagrams when they simplify the explanation, such as when showing a process or the relationships among concepts.

 Address only one complete idea. Keep the concept topic concise, but describe everything that the user needs to understand to be successful.

 Provide links to closely related concept, task, and reference topics.

43 Authoring with DITA XML

IBM User Technologies Example  Authoring a concept topic

44 Authoring with DITA XML

IBM User Technologies Authoring reference topics  Guidelines  Demonstration

45 Authoring with DITA XML

IBM User Technologies Reference topics  Write reference topics to provide quick access to facts that users need while they carry out their tasks.  Use a noun or noun phrase as the heading.

 For a particular category of information, such as API documentation, use a consistent format so users can find what they want to know quickly.  Be brief, but write in full sentences. © 2005 IBM Corporation

46 Authoring with DITA XML

IBM User Technologies Reference topics (continued)  Do not go into long explanations; assume that readers understand the basic technology.

 Make the topic as long as it needs to be to cover the subject.

 Provide links to closely related reference topics and, in some cases, to related concept and task topics.

47 Authoring with DITA XML

IBM User Technologies Example  Authoring reference topics

48 Authoring with DITA XML

IBM User Technologies Summary    Topics have a specific structure Good topics are useless if they can’t be found, so making them retrievable is important Methodologies for creating content also tell us how to organize them  The DITA document types encourage good writing, but aren’t enough on their own – you still need guidelines, good writing skills, and most importantly an understanding of your audience and subject matter © 2005 IBM Corporation

49 Authoring with DITA XML

IBM User Technologies Questions and comments

50 Authoring with DITA XML