enterprise content metamodel: information type definitions
DESCRIPTION
Enterprise Content Metamodel: Information Type Definitions. Specialization Focus Area Rob Hanna September 22, 2010. Agenda. Introduction Describe Business Document Environment Introduce 3 Content Models DITA Information Model Information Mapping® Enterprise Content Metamodel. - PowerPoint PPT PresentationTRANSCRIPT
DITA for Enterprise Business Documents Subcommittee
Enterprise Content Metamodel: Information Type Definitions
Specialization Focus AreaRob Hanna
September 22, 2010
DITA for Enterprise Business Documents Subcommittee
Agenda
• Introduction• Describe Business Document Environment• Introduce 3 Content Models– DITA Information Model– Information Mapping®– Enterprise Content Metamodel
DITA for Enterprise Business Documents Subcommittee
Presentation Objectives
• Explore three known information models• Discuss merits of each leading to decisions on:– whether one is best suited to the efforts of the
subcommittee; or– if a new model needs to be developed
DITA for Enterprise Business Documents Subcommittee
Specialization Focus Area
• The goal of the Specialization Focus Area is to make recommendations for structural and domain specializations needed to support enterprise business documents
• The first task is to identify potential new information types that would require structural specialization
• Once the information types have been determined, the Focus Area will examine specific domain specializations common across all information types in this domain
DITA for Enterprise Business Documents Subcommittee
Objectives for the Metamodel
• Develop a universal metamodel to describe typical business document content
• Identify reusable semantic structures with a compatible granularity to the DITA standard
• Describe a framework for adoption of a DITA standard for enterprise business documents
DITA for Enterprise Business Documents Subcommittee
Business DocumentsTypically include controlled items such as:
• Policies and procedures• Product
development/maintenance documentation
• Technical publications• Sales and marketing
materials
Typically do not include items such as:
• Memoranda and correspondence
• Newsletters and social media
• Third-party materials• Database and financial
outputThese items along with business documents represent business records
DITA for Enterprise Business Documents Subcommittee
Research
• Content Models– Information Mapping®– DITA
• Document Models– Military Specifications (S1000D, 2361, 2167, 498)– ISO (9000, 15489)
• Business Object Models– Rational Unified Process/Unified Modeling Language– Zachman Framework– Information Technology Infrastructure Library (ITIL)
DITA for Enterprise Business Documents Subcommittee
Nature of Business Documents
• Business documents are– a conglomeration of different types of information– managed using extensive metadata– process-driven– referenced by content used elsewhere in the process
• While there are no widely adopted standards for content models, there are typical document types and recognizable structures in most business documents
DITA for Enterprise Business Documents Subcommittee
Accountability
• A convergence of factors are driving business towards– process certification,– regulatory requirements,– needs for improved efficiency, and– measurable quality
• These demands require– better metadata,– finer granularity of information,– centralization,– process automation,– information ownership, and– traceability
DITA for Enterprise Business Documents Subcommittee
Knowledge Management
• Knowledge is rarely captured directly in business documents and is most often compiled indirectly by document authors
• Information is gathered from multiple sources and subject matter experts and distilled into documents before it is thrown over the wall – the information is written and forgotten about
• Over time, the knowledge loses relevance or is lost• The metamodel breaks content down into manageable
chunks that can be controlled by the subject matter experts and compiled into traditional documents
DITA for Enterprise Business Documents Subcommittee
Unified Content Strategy
• Single-source authoring– has reached a state of maturity within technical
publications– enable collaboration on content creation– Improves
• content quality,• consistency, and• maintainability
– requires a level of sophistication that eludes most business users
DITA for Enterprise Business Documents Subcommittee
Granularity
• Granularity of reuse within business documents appears to be more complex than in typical technical publications– Size of reusable components varies from a single-statement to
collections of nested topics– Application of reusable components may be used across far
more diverse audiences
• Granularity must be defined as well by the ownership and lifecycle of the component within the metamodel
• Information must be captured into a single source and managed according to robust rules for reuse using progressive disclosure to determine the granularity
DITA for Enterprise Business Documents Subcommittee
Evolution of the Enterprise Topic
• What is a topic?– fundamental building blocks used to capture knowledge
about any given subject– a single definitive source of information– designed to be used and reused in their entirety or in
part– independent of any containing document or map and
can be used in any appropriate context
DITA for Enterprise Business Documents Subcommittee
Content Lifecycle
• Typical content lifecycle describes documents developed and stored in a repository
• Topic-based lifecycle is similar in that documents are planned developed and stored in a repository as topics that can be reused
• Enterprise Business Content Lifecycle describes a different process where topics are developed and stored in a repository. Documents are then created as needed using topics in the repository.
DITA for Enterprise Business Documents Subcommittee
Enterprise Business Content Lifecycle
Input: Topics
Output: Information
ProductRepository: Information
Core
DITA for Enterprise Business Documents Subcommittee
Reusability
DITA for Enterprise Business Documents Subcommittee
Traceability
DITA for Enterprise Business Documents Subcommittee
Traceability
• Businesses use many purpose-built applications and databases to manage business information such as:– Requirements management tools– Bug tracking systems– Software testing tools
• The metamodel should incorporate traceability for business documents to integrate with these systems
DITA for Enterprise Business Documents Subcommittee
Traceability in the Enterprise
• Traceability is normally driven subjectively by the author creating cross-references and links to related content he or she is has written or is aware of
• Content that flows together goes together in a document as it is created
• Where content is topic-based rather than document-based, traceability to enterprise content is considerably more difficult without business rules for relationships
• The metamodel establishes basic rules for traceability based upon the common flow of information in an enterprise with dependencies and ancestry
DITA for Enterprise Business Documents Subcommittee
Content Classes
• Early on in the discussion on topic specializations, the focus area discovered that content needed to be broken down into classes to describe its properties and behaviours
• DITA had first dealt only with one class of content – the topic – which was a standalone chunk of content that existed outside of any single document
• New innovations such as the DITA Bookmap introduced classes of content that did not fit with this description
• This focus area has categorized content into four classes that describe the different properties of content
DITA for Enterprise Business Documents Subcommittee
Content Classes I & II
• Class I Content– Represents portable, non-contextual information topics
living outside of documents. Class I Content requires specific sub-structures unique to the topic type.• For example: DITA concept, task, and reference
• Class II Content– Represents non-portable, contextual information topics
that resides only within a given document. Class II Content requires very general, common sub-structures. • For example: Executive summary, chapter summary, document
foreword, dedication, etc
DITA for Enterprise Business Documents Subcommittee
Content Classes III & IV
• Class III Content– Represents boilerplate text that can reside outside of a
content repository and may be produced automatically at publishing time.• For example: Legal disclaimer, company information, table of
contents, index, advance organizer, cover page, etc
• Class IV Content– Represents content needed to aggregate documents
from the three previous classes of content including metadata about the document.• For example: DITA map or bookmap
DITA for Enterprise Business Documents Subcommittee
Information Models
• To identify the necessary information types needed to support business documents, the focus area will study available information models– DITA information model
• Breaks information types into Topics
– Information Mapping®• Breaks information types into Information Modules
– Information Management Model• Breaks information types into Information Objects
• This is not necessarily an exhaustive list of models and others may be looked at as they surface
DITA for Enterprise Business Documents Subcommittee
1) The DITA 1.0 Information Model• DITA was designed to support
Task-based authoring methodology for end-user documentation
• This approach consists primarily of identifying specific tasks users need to perform to be successful with their product
• Concept and reference information is added to supplement the tasks and give the user better understanding of the product to improve likelihood of success
Alarm Clock User Guide
About Alarm Clocks
Setting Clock
Setting Wake Up Alarm
Setting Radio Alarm
Installing Batteries
Radio Settings
Battery Specifications
DITA for Enterprise Business Documents Subcommittee
DITA Information Types
• Class I– Procedural
• Task
– Descriptive• Reference
– Explanatory• Concept• GlossEntry
DITA for Enterprise Business Documents Subcommittee
DITA Bookmap
• The Bookmap introduces new placeholders for topics that don’t ideally fit with the initial concepts of topics (or Class I Content) such as:– Class II Content – contextual content for the specific document
• <dedication>• <bookabstract>• <preface>
– Class III Content – boilerplate text common to many documents• <notices> • <colophon>
DITA for Enterprise Business Documents Subcommittee
Limitations
• While DITA can be manipulated to suit any output, it is often done at the expense of maintaining useful semantic mark up and consistency of content
• Many DITA adopters have limited their deployment of information types to Concept and Task, where Task covers all procedural information and Concept covers everything else
• Extension beyond task-based information types is highly desirable
DITA for Enterprise Business Documents Subcommittee
2) The Information Mapping® Approach
• Owned by Information Mapping International nv of Belgium http://www.informationmapping.com/en
• A scientifically-based method of structured communication• Developed by Harvard researcher and based on 40 years of
research and application• Applied to all communication media - paper and electronic• Used in 30+ countries around the world• Communicates any and all complex information
DITA for Enterprise Business Documents Subcommittee
Information Types (1 Block = 1 Purpose)
• Categorize information based on its purpose for the user• Answer all user questions on any topic• Defined by one of six Information Types
DITA for Enterprise Business Documents Subcommittee
Content Modules
The results are content modules - precisely tagged pieces of metadata –
that can be snapped together in any pattern to create an endless variety of
documents
DITA for Enterprise Business Documents Subcommittee
Document 1
The information blocks can combine like this ...
DITA for Enterprise Business Documents Subcommittee
Document 2
Or like this, without rewriting any of them.
DITA for Enterprise Business Documents Subcommittee
Information Types
User question
“What is the (value)?”
“What must I do?”
“How do I do it?”
“How does it work?”
“What does it look like?”
“What is it?”
Information Type
Fact
Principle
Procedure
Process
Structure
Concept
DITA for Enterprise Business Documents Subcommittee
Presentation Modes for Information Types
Each of the 6 Information Types has its own best way of presentation that visually reflects the purpose
of that Type.
DITA for Enterprise Business Documents Subcommittee
Example
• Content objects defined by their purpose or Information Type
Fact
Fact
Fact
Process
Process
DITA for Enterprise Business Documents Subcommittee
Presenting Fact
This FACT block…
re-displayed as…
DITA for Enterprise Business Documents Subcommittee
This PROCESS block…
Presenting Process
re-displayed as…
DITA for Enterprise Business Documents Subcommittee
… here published in a paper document …
The results are tagged content objects …
… and displayed for easy comprehension.
Result
DITA for Enterprise Business Documents Subcommittee
Challenges
• Information Mapping® models content at a different level of granularity to DITA
• Information Mapping® focuses on the appearance of the rendered content more than the semantic markup of the source content
• Information Mapping® isn’t widely used for structured authoring with XML
• The methodologies are proprietary and any use of their approach may be limited
DITA for Enterprise Business Documents Subcommittee
3) The Enterprise Content Metamodel
• Created in 2002 by Rob Hanna• Published in 2005 STC Conference Proceedings as the
Information Management Modelhttp://www.ascan.ca/stc/whitepaper_imm.pdf
DITA for Enterprise Business Documents Subcommittee
Scope
• The Enterprise Business Metamodel– is designed specifically for business documents– attempts to integrate with rather than replace existing
information systems– is not intended to dispense with vast amounts of
dissimilar or unstructured information used within an enterprise
DITA for Enterprise Business Documents Subcommittee
Modeling Enterprise Content
• The model started as a map of dozens of dissimilar types of content found within an enterprise linked in various ways through traceability
• For example– RFP elements were linked to proposal elements– Proposal elements were linked to requirement elements– Requirement elements were linked to design elements– Design elements were linked to specification elements– Specification elements were linked to procedural elements
• As information changed in one element, other elements within the chain were impacted
DITA for Enterprise Business Documents Subcommittee
Traceability of Class I Content
• The model is based upon the traceability of information as it changes within an environment
• Within any business, information changes regularly that impacts other sources of information
• The model follows these changes from one information type to another as it may appear in any environment
• The model deals strictly with Class I Content types
DITA for Enterprise Business Documents Subcommittee
Model Construction
• This model breaks down into 11 information types describing enterprise content
• Each of the 11 types can be specialized into more specific types as needed
• While not modeled after DITA, it shares very similar characteristics and should prove to be entirely compatible
• Information types fall into one of four categories answering the “How”, “Who”, “What”, and “Why”
DITA for Enterprise Business Documents Subcommittee
Who? What?How?
Why?
Enterprise Content Metamodel
Task
Concept
Governance
Event
ReferenceActivity
Resource
Ability
Requirement
Design
Objective
Proposed
Resource Event Event ObjectiveWhere? When?
Standard DITAStandard DITA
Task
Concept
Reference
DITA for Enterprise Business Documents Subcommittee
Info Type Synonyms and Specializations
Business Information Types• Objective: Goal, Mission, Plan, Purpose, Aim, Course, Intention,
Project, Target
Intellectual Information Types• Concept: Term, Definition, Idea, Image, Theory, Principle, Opinion,
Generalization• Governance: Policy, Rule, Guidelines, Tip, Warning, Legislation, FAQ,
Code• Task: Action, Procedure, Process, Instruction, Method, Mode, Routine• Event: Report, Result, Incident, Issue, Outcome, Case, Scenario,
Narrative, Essay, Background
DITA for Enterprise Business Documents Subcommittee
Info Type Synonyms and SpecializationsHuman Information Types• Role: Resource, Person, Group, Team, Company, Persona, Community,
Place, Facility• Activity: Commitment, Task, Contract, Obligation, Duty, Function,
Service• Ability: Skill, Experience, Capability, Behaviour, Measure, Scale,
Capacity, Competency
Physical Information Types• Requirement: Need, Requirement Specification, Condition, Criterion,
Requisite• Design: Outline, Code, Model, Plan, Flowchart, Diagram, Layout,
Schema, Architecture, Logic, Design Specification• Reference: Item Specification, Gap, Description, Object,
Representation, Feature, Function
DITA for Enterprise Business Documents Subcommittee
Task-based Information• The Task information type
is central to the model• Task describes how
something is performed• Reference describes the
tools used in the Task• Task produces an Event
• Activity describes what is to be performed by the Task
• Governance describes limitations on the Task
• Concept provides terms for Governance
Task
Concept
Governance
Event
ReferenceActivity
DITA for Enterprise Business Documents Subcommittee
Task Type
• Description– Based on the DITA Task topic type– Describes one or more steps needed to accomplish an action
• Dependencies– Reference– Governance– Activity– Event
• Examples– User procedures and Instructions– Processes– Test cases
Task
Concept
Governance
Event
ReferenceActivity
DITA for Enterprise Business Documents Subcommittee
Task Construction
Sample Markup<task> <title></title> <shortdesc></shortdesc> <taskbody> <prereq></prereq> <steps> <step><cmd></cmd></step> <step><cmd></cmd></step> </steps> </taskbody> <related-links></related-links></task>
Task can be used to create both procedure and process content.
Sample ContentLog onto the networkOnce logged on to the network, you will be able to work online.You must have received log-in details from IT before proceeding with your log-in attempt. Caution: Do not attempt to log onto the network without current login credentials.1. Press <CTRL> + <ALT> + <DELETE>2. Enter user name and password3. Click EnterSee also:• Login Attempts
Task
Concept
Governance
Event
ReferenceActivity
DITA for Enterprise Business Documents Subcommittee
Event Type
• Description– Describes an event– Consists of an event along with optional date/time, place, summary,
description, status, acceptability, and recommendation
• Dependencies– Task– Objective
• Examples– Test results– Problem/incident report– Activity report
Task
Concept
Governance
Event
ReferenceActivity
DITA for Enterprise Business Documents Subcommittee
Task
Concept
Governance
Event
ReferenceActivity
Event Construction
Sample Markup<event> <title></title> <summary> <date/> <location/> </summary> <eventbody> <eventdetails></eventdetails> <acceptability></acceptability> <recommendations></recommendations> </eventbody> <related-links/></event>
Sample ContentLogin attempt failed10/03/2008: User was unable to log onto the network with verified login credentials.User attempted to log onto the OASIS network through Abacus using his most recent login information contained in a system email. The system gave the user the following error message:ERROR: Cannot log onto DNS server. User account mismatch on file.This is not the expected behaviour for a user login.Check the PKI domain tables to ensure the settings are correct for this user.See also:• QA-02512 Steps to reproduce error
DITA for Enterprise Business Documents Subcommittee
Governance Type• Description
– Applies conceptual information providing guidance or limitations on performing Tasks
– Consists of a statement along with optional conditions, scope, remedies, consequences, and background information
• Dependencies– Concept [Parent]: Changes may prompt changes to
Governance– Task [Child]: Changes to Governance may prompt changes to
Task• Examples
– Cautions, warning, and notes– Policies– Guidelines
Task
Concept
Governance
Event
ReferenceActivity
DITA for Enterprise Business Documents Subcommittee
Governance Construction
Sample Markup<governance> <title></title> <statement></statement> <govbody> <conditions></conditions> <penalties></penalties> <remedies></remedies> </govbody> <related-links/></governance>
Sample ContentLogin AttemptsDo not attempt to log onto the network without current login credentials.After 10 failed login attempts, the system will lockout your workstation and prevent it from connecting to the network.If your workstation is locked out, contact the IT Service Desk for assistance.See also:• Log onto the network
Task
Concept
Governance
Event
ReferenceActivity
DITA for Enterprise Business Documents Subcommittee
Concept Type
• Description– Based on the DITA Concept topic type– Defines and explains terms used
• Dependencies– Objective [Parent]: Changes may prompt changes to Concepts– Guidance [Child]: Changes to Concept may prompt changes to
Governance
• Examples– Definitions– Industry Standards– Whitepapers
Task
Concept
Governance
Event
ReferenceActivity
DITA for Enterprise Business Documents Subcommittee
Concept Construction
Sample Markup<concept> <title></title> <shortdesc></shortdesc> <conbody> <paraclass/> </conbody> <related-links/></concept>
Sample ContentSecure PasswordsSecure passwords ensure that intruders are unable to assume your identity and compromise network security.Secure passwords can take many forms. Generally, passwords should be more than six characters long, any less and the ability to crack the password increases by 425%, according to NetSpy. Consider passwords that include a mix of alpha characters and numbers.See also:• Network Password Policy• Login Attempts
Task
Concept
Governance
Event
ReferenceActivity
DITA for Enterprise Business Documents Subcommittee
Resource-based Information
• Activity describes what is to be performed
• Activity is performed by a Resource
• Activity requires a certain Ability
• Resource possesses given Ability
Task
Concept
Governance
Event
ReferenceActivity
Activity
Resource
Ability
DITA for Enterprise Business Documents Subcommittee
Activity Type• Description
– Describes what needs to be accomplished and criteria for measuring performance
– Does not describe “how” it is to be done (see Task)– Consists of an item along with optional summary, description,
constraints, and evaluation criteria• Dependencies
– Resource [Parent]: Changes to Resource may prompt changes– Ability [Child]: Changes to Activity may require new Abilities– Task [Child]: Changes to Activity may require new Tasks
• Examples– Job description– Service Level Agreement– Action items
Activity
Resource
Ability
DITA for Enterprise Business Documents Subcommittee
Activity Construction
Sample Markup<activity> <title></title> <shortdesc></shortdesc> <activitybody> <details></details> <constraints></constraints> <criteria></criteria> </activitybody> <related-links/></activity>
Sample ContentSetting Up Account for New HiresNetwork accounts are to be set up prior to the first day of work for new-hires.New accounts are created when triggered by the New Hire Process. A problem ticket will arrive and be resolved by the IT Service Desk.New hires that are not subject to the New Hire Process may not have accounts set up during their first week of work.The IT Service Desk requires seven-days notice for new account setup.See also:Service Desk Specialist
Activity
Resource
Ability
DITA for Enterprise Business Documents Subcommittee
Resource Type
• Description– Identifies a Resource within an organization– May be a named person, job role, department, or other group of
related persons– Consists of a name along with optional details and hierarchy
• Dependencies– Objective [Parent]: Changes to Objectives may modify Resources– Activity [Child]: Resources are responsible for given Activities– Ability [Child/Parent]: Resources possess and/or require Abilities
• Examples– Biographical information– Description of organization– Contact record
Activity
Resource
Ability
DITA for Enterprise Business Documents Subcommittee
Resource Construction
Sample Markup<resource> <name></name> <shortdesc></shortdesc> <resourcebody> <details></details> <characteristics> </characteristics> </resourcebody> <related-links/></resource>
Sample ContentService Desk SpecialistThe Service Desk Specialist is a member of the IT Service Desk. This role is typically the first-line of response to customer inquiries and complaints.The Service Desk Specialist reports to the Service Desk Shift Supervisor and may be responsible for supervising Co-Op placements and new-hires.Core competencies:• English/French, Fluent Spoken,• Intermediate ITIL CertificationServices include:• Registering Incidents,• Setting Up AccountsSee:• Sue Green
Activity
Resource
Ability
DITA for Enterprise Business Documents Subcommittee
Ability Type
• Description– Describes level of competency required for performing tasks– Consists of a competency along with optional summary,
description, level, and evaluation criteria
• Dependencies– Resource [Parent/Child]: Resources possess and/or require
Abilities– Activity [Parent]: Changes to Activities may require changes to
Abilities
• Examples– Competency matrix– Employee evaluation– Training plan
Activity
Resource
Ability
DITA for Enterprise Business Documents Subcommittee
Ability Construction
Sample Markup<ability> <title></title> <shortdesc></shortdesc> <abilitybody> <details></details> <constraints></constraints> <criteria></criteria> </abilitybody> <related-links/></ability>
Sample ContentMultilingualismAn ability to communicate in more than one language.At ABC, Corp. employees may be required to work in the native language of our customers and partners.Competency levels are divided by the number of languages and fluency in each language.Languages spoken at ABC, Corp. other than English include:• French,• Cantonese, and• SpanishCompetency Levels:• English/French, Fluent Spoken• English/French, Fluent Written Spoken
Activity
Resource
Ability
DITA for Enterprise Business Documents Subcommittee
Product-based Information
• Reference describes a tool and its benefits and features
• Design describes how the tool is built to Requirements
• Requirement governs Design and functionality
Reference
Requirement
Design
Task
Concept
Governance
Event
ReferenceActivity
Resource
Ability
DITA for Enterprise Business Documents Subcommittee
Reference Type• Description
– Based on DITA Reference topic type– Describes details, features, and/or facts about an object
• Dependencies– Requirement [Parent]: Changes to Requirements may produce gap
specifications– Design [Parent]: Changes to Design may prompt changes to the
Reference topic– Task [Child]: Changes to the Reference may prompt changes to
related Tasks• Examples
– Product specification– Screen capture with callouts– Publication specification
Reference
Requirement
Design
DITA for Enterprise Business Documents Subcommittee
Reference ConstructionSample Markup<reference> <title></title> <shortdesc></shortdesc> <refbody> <example></example> <characteristics> </characteristics> <section></section> </refbody> <related-links/></reference>
Sample ContentPM_1202: Network Login DialogDialog permits users to enter account credentials and submit them for network verification to establish a connection. ┌─User Login ───────────────────┐ │User:_________________________ │ │Password:_____________________ │ │ SUBMIT CANCEL │ └───────────────────────────────┘Field Description Note User Enter name Not Case Sent Password Enter password Case SensitiveAPI CallsThe dialog can be accessed using the following API call: LaunchLogDia.Run.UISee also:• PMCS 90022: NetLog.corba
Reference
Requirement
Design
DITA for Enterprise Business Documents Subcommittee
Design Type• Description
– Explains how something is designed to work– Does not describe how it is (see Reference)– Consists of an item along with optional inputs, outputs, parameters,
description, limitations, and logic• Dependencies
– Requirement [Parent]: Changes to Requirements may prompt changes to the Design
– Reference [Child]: Changes to Design may prompt changes to the Reference topic
• Examples– Preliminary/Detailed Design– Logic diagrams– Content Plan
Reference
Requirement
Design
DITA for Enterprise Business Documents Subcommittee
Design Construction
Sample Markup<design> <title></title> <shortdesc></shortdesc> <designbody> <paraclass/> </designbody> <related-links/></design>Design topics represent information used by developers, and product designers to create products. It describes how something works on an abstract level. This can represent a large number of specializations to accommodate design of software, hardware, drugs, publications, etc. At its most basic level, there are few specialized elements.
Sample ContentPMCS 90022: NetLog.corbaModule displays login dialog and submits data to DNS server for routing.Inputs• userName.pki• userPass.pksInterface• DNSPass.pk.corbaLogicFunction NetLog() { Go.Log(userName,userPass); If Go.Log = “Pass” then { Goto.DNSPass; } else end;}See also:• PM_1202: Network Login Dialog
Reference
Requirement
Design
DITA for Enterprise Business Documents Subcommittee
Requirement Type• Description
– Describes what an object must do– Does not describe what the object does (see Reference) nor how it
should do it (see Design)– Consists of a statement along with optional description, parameters,
dependencies, performance and ranking• Dependencies
– Objective [Parent]: Changes may prompt changes to the Requirement– Design [Child]: Changes may prompt changes to the Design– Reference [Child]: Changes to the Requirement may prompt changes
to the Reference topic (particularly where there is no Design)• Examples
– Product Requirement Specification– RFP elements– User needs analysis
Reference
Requirement
Design
DITA for Enterprise Business Documents Subcommittee
Requirement Construction
Sample Markup<requirement> <title></title> <need></need> <reqbody> <details></details> <constraints></constraints> <criteria></criteria> </reqbody> <related-links/></requirement>Service objects and Governance objects are very similar. The main distinction is that a Service object applies to a Resource whereas a Governance object does not apply to a specific Resource as it applies to everyone. A Service is a commitment made by a Resource.
Sample ContentUnique User LoginEach user must be able to log onto the network using a secure password and assigned user name.Before working on the network, the user must submit a valid login to the network server for validation. The system shall provide appropriate user-feedback for incorrect login attempts.Group logins shall not be permitted.If the user repeatedly fails login attempts, the system shall prevent further connection attempts.See also:• PM_1202: Network Login Dialog• PMCS 90022: NetLog.corba
Reference
Requirement
Design
DITA for Enterprise Business Documents Subcommittee
Business-based Information• Objective
describes the goals, business reasons, or mission affecting change
• Resources, Concepts, and Requirements are suited to meet an Objective
• Objectives may be related to previous Events
Objective
Resource Concept Requirement
Task
Concept
Governance
Event
ReferenceActivity
Resource
Ability
Requirement
Design
Event
DITA for Enterprise Business Documents Subcommittee
Objective Type
• Description– Describes the goals of an organization, project, product, or idea– Consists of a goal along with optional description, evaluation
criteria, target date
• Dependencies– Resource, Concept, and Requirement [Child]: Changes to an
Objective may prompt new child topics– Event [Parent]: Results may alter or prompt for new Objectives
• Examples– Project planning elements– Employee performance plan– Corporate charter
Objective
Resource Concept Requirement
DITA for Enterprise Business Documents Subcommittee
Objective Construction
Sample Markup<objective> <title></title> <goal><goaldate/></goal> <objectivebody> <details></details> <constraints></constraints> <criteria></criteria> </objectivebody> <related-links/></objective>
Sample ContentImprove IT Security PracticesQ2 2009: Corporate IT will develop new policies and procedures to improve security practices in preparation for ISO:27001 audit.
Objective
Resource Concept Requirement
DITA for Enterprise Business Documents Subcommittee
Abstract Information Types
• Upon examination of the semantic substructures for these 11 content types, we identified similarities between several of the types precipitating the creation of 6 abstract information types
• The abstract information types are derived directly from the base topic type and form the basis for all information contained within the model
• Explanatory• Procedural• Descriptive• Advisory• Criterial• Temporal
DITA for Enterprise Business Documents Subcommittee
Information Type Similarities
• Advisory– Governance
• Chronological– Event
• Criterial – Objective– Requirement– Ability– Activity
• Procedural– Task
• Explanatory– Concept– Design
• Descriptive– Reference– Resource
DITA for Enterprise Business Documents Subcommittee
Inheritance from Abstract LayerBase
Topic
Abstract
ExplanatoryAbstract
DescriptiveAbstract
ProceduralAbstract
DirectiveAbstract
CriterialAbstract
Temporal
Tech Pubs
ConceptTech Pubs
ReferenceTech Pubs
Task
Bus Docs
ConceptBus Docs
ReferenceBus Docs
TaskBus Docs
GovernanceBus Docs
ObjectiveBus Docs
Event
Bus Docs
DesignBus Docs
ResourceBus Docs
Requirement
Bus Docs
Ability
Bus Docs
Activity
DITA TC
TechPubs
BusDocs
Advisory
DITA for Enterprise Business Documents Subcommittee
Business Document Examples
• The objects described in the model can be used to create business documents
• Business documents will contain a mix of content classes but will primarily consist of Class I content
• The traceability and reuse potential for many of the objects is substantial
• Presenting three possible examples:– Request for Proposal (RFP)– Software Incident Report– Meeting Minutes
DITA for Enterprise Business Documents Subcommittee
Request for Proposal (RFP) example
• Class I Content– Objective Object describes the goals of the RFP process– Concept Objects define the terms used– Governance Objects define the rules of engagement– Activity Objects describe who is responsible for what– Task Objects describe the process for submittal– Objective Object describes the background for the RFP– Requirement Objects describe each required element
for the RFP respondent
DITA for Enterprise Business Documents Subcommittee
Software Incident Report example
• Class I Content– Event Object documents the incident– Role Object identifies the user– Activity Object describes what the user was trying to
accomplish– Task Object lists the steps taken to reproduce the
incident– Reference Object describes the impacted systems– Reference Object describes the system error
DITA for Enterprise Business Documents Subcommittee
Meeting Minutes example
• Class I Content– Objective Objects describe the meeting agenda– Role Objects identify participants– Event Objects document discussions– Objective Objects describe recommendations stemming
from discussions– Activity Objects list action items for Role Objects– Objective Objects (for action) and/or Concept Objects
(for information) describe new business– Governance Objects (requiring immediate action) or
Objective Objects (for future action) describe motions