intro it stc
TRANSCRIPT
Shameless PlugTech pubs since '95, speaker since '98New web site at www.davegash.comSan Diego based, do onsite and offsite
work, plus conferences in US and abroadTrain & consult on user assistance,
online publishing, and related technologies: HTML, CSS, XML/XSLT, DITA, JavaScript, etc.
Email: [email protected]
Session overviewIntroduce information typing
Concepts and benefits
Explore primary componentsTopics, topic types, relationships
Work through the processImprove poorly written content by applying
Information Typing
Summary, resources
What this session is not…tool-centric
Information Typing is a technique, not a technology
…about DITADITA is focused on IT, but not vice versa
…code-yWell, that's a change!
What is information typing?A definition
Couldn't find one I liked; here's mine:The identification, classification, and separation of
content blocks (chunks) into discrete categories, where each category has a specific function, structure, and presentation in the content set.
We'll use that concept as it applies to UA
Untyped authoring
Content
Content
Content
Content
Content
Content
Content
Content
Content
Content
Untyped authoringReaders miss structural clues
They hit topics not knowing what to expectMust read content to determine content type,
i.e., whether the content meets their needs
Writers lose consistency of useAny topic might contain any contentDuplicate content too easy to createHard to locate and maintain later
Typed authoring
Content
Content
Content
Content
Content
Content
Content
Content
Content
Content
Typed authoringReaders have clear structural clues
Know what's behind links before clickingSaves time, reduces searching and backtracking
from "not quite right" topics
Writers gain consistencyTopics have standardized look & feelDuplicate content more easily avoidedStructure makes maintenance easier
Why should we use IT?Benefits for your company
Improved document quality & consistency More author productivity Better (maybe first ever) content sharing/reuse Less content duplication More output device flexibility Lower costs: personnel, software, storage,
support, maintenance, localization
Why should we use IT?Benefits for writers and users
Reuse content across docs, doc sets, deliverables Ease of maintenance Reduced copy/paste error propagation Improved comprehension and retention Better access, navigation, precision Perceived consistency, mental model of content
Basic IT content unit is topicTopics contain…
Only information essential* for user to understand current subject
Only information pertinent to context (IT)Links to related, non-essential* information
*subjective, depending on topic
Types of topics that matter in IT
IT topic types: C T RConcept: why?
Provides background information
Task: how?Provides ordered instructionsPrimary topic type; most topics will be tasks
Reference: what?Provides technical details
Are there other types?Sometimes…
Overview, glossary, marketing, troubleshooting, welcome, FAQs, "topic"
…but avoid themIf you have content that doesn't fit C T R types,
it probably doesn't belong in your help system
Concept topicAnswers why questions
Defines prerequisites for taskReveals importance of taskExplains effect/impact of task
Concept topic example
About Parental Controls
Establishing parental control of TV ratings helps protect your family from viewing undesirable or inappropriate programs. GalaxyDVR lets you set which TV ratings levels your DVR can access.
Using a Personal Identification Number (PIN) ensures that this setting can only be changed by you or someone you trust. The PIN you choose should be easy to remember but hard to guess.
Programs that are restricted by a PIN cannot be viewed on the DVR by anyone, even you, without first entering the correct PIN.
Related topics:Setting a PIN and TV RatingPINs and Rating Levels
Why do this?
Why is this important?
What is the effect?
22
Related topics
Task topicAnswers how questions
Provides brief lead-in to taskDefines ordered steps of taskExposes intermediate/final results of task
Task topic example
Setting a PIN and TV Rating
To control access to program viewing:
1. In the Parental Controls group, enter a PIN in the PIN field.
2. In the Apply to Programs Rated dropdown, choose the lowest TV Rating Level to which you wish to apply parental control.
3. Click the Save button.
Your PIN and Rating Level are saved and linked to your DVR.
Related topics:About Parental ControlsPINs and Rating Levels
Brief lead-in
How do I do this?
What is the result?
Related topics
Reference topicAnswers what questions
Provides detail/examples without expositionDescribes requirements/syntax of app elementsLists potential errors/input restrictions
PINs and Rating Levels
PINs must consist of one to four numerics digits (0-9), and cannot contain letters, spaces, or special characters (+, &, *, etc.).
Parental control is applied to the selected Rating Level and all higher rating levels. For example, if you restrict programs rated TV-14, programs rated TV-MA will also be restricted; if you restrict programs rated TV-PG, programs rated TV-14 and TV-MA will also be restricted.
TV-Y7 is the lowest selectable rating level. You cannot apply parental control to programs rated TV-Y.
Related topics:About Parental ControlsSetting a PIN and TV Rating
Reference topic example
Requirements/syntax
Plain detail/examples
Input restrictions
Related topics
Recall IT definition
Each topic typePerforms a specific job in the doc setFollows a specific internal arrangementExhibits a specific layout format
But in the real world…IT for new topics not too hard
Easy to identify information types for new content
IT for legacy topics can be challengingLegacy documents are usually linear & untypedExisting topics often conflate information typesContent from developers can be mixed
That's okay – it's not their job, it's ours
Sometimes easy to fix
How to set a PIN
GalaxyDVR lets you set which TV ratings levels your DVR can access. PINs must consist of one to four numeric digits (0-9), and cannot contain letters, spaces, or special characters (+, &, *, etc.).
1. In the Parental Controls group, enter a PIN in the PIN field.2. In the Apply to Programs Rated dropdown, choose the lowest TV Rating Level to which you wish to apply parental control.3. Click the Save button.
PINs are applied to the selected Rating Level and all higher rating levels. Using a Personal Identification Number (PIN) ensures that this setting can only be changed by you or someone you trust.
TV-Y7 is the lowest selectable rating level. You cannot apply restrictions to programs rated TV-Y.
C / T / R
Sometimes not so much
How to set a PIN
GalaxyDVR lets you set which TV ratings levels your DVR can access. You cannot apply restrictions to programs rated TV-Y.
Enter a PIN (numbers only), and choose the lowest TV Rating Level to which you wish to apply parental control.
Using a Personal Identification Number (PIN) ensures that this setting can only be changed by you or someone you trust. Be sure to click Save so your PIN is linked to your DVR.
Establishing parental control of TV ratings helps protect your family from viewing undesirable or inappropriate programs.
W / T / F
How do we handle that?To apply IT to legacy content
Start with a muddled topic or documentIdentify the information types of the contentRemove or save unrelated contentEdit content as necessaryCreate new C T R topics with correct content
Legacy process
Concept
Task
Reference
One more important pointC T R isn't always 1:1:1
Concept topics often support multiple tasksTask topics often rely on multiple reference topicsReference topics often link to multiple references
Base new/rewrite doc on tasksIdentify tasks first, then locate support contentVisual is good: draw a relationship tableWrite discrete topics so they can be reusedTasks are most critical to users and management
Summary Information Typing is:
Well named; assigns types to units of informationNot a technology; a content management conceptNot tool-specific; can be used with any HATBeneficial to companies, writers, and usersConducive to saving time/effort/moneyEasier with new content than legacy contentAbsolutely invaluable skill for technical writersClosely linked to DITA – but that's okay
Resources Books
Introduction to DITA - A User Guide to the Darwin Information Typing Architecture (Linton & Bruski)
DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA (Bellamy, Carey, & Schlotfeldt)
Every Page Is Page One: Topic-Based Writing for Technical Communication and the Web (Baker)
SitesWikipedia: Darwin Information Typing ArchitectureJacquie Samuel's techwhirl.com/getting-started-with-
topic-based-writing/Kai Weber's kaiweber.wordpress.com/category/topic-
based-authoring-2/