220 working with a style guide within dita
TRANSCRIPT
-
8/10/2019 220 Working With a Style Guide Within DITA
1/15
-
8/10/2019 220 Working With a Style Guide Within DITA
2/15
2
A Style Guide for
Authoring Documents in DITA
What is DITA again?
DITA is a new open standard for the
documents such as policies and procedures,teaching and learning documents, Helpsystems, Web sites and instruction manuals.
DITA is many things in one. It is:
a writing methodology
a topic-based information architecture
a structured authoring platform.
-
8/10/2019 220 Working With a Style Guide Within DITA
3/15
3
For Tech Writers...
The DITA approach utterly separatescontent from its presentation by usingdocument semantics as the basis formark-up.
It takes a modular approach
methods of:
linear writing
style-based markup
Two differences to focus on
Separation of content and form
Author not concerned with presentationalform
Modularity Documents written as re-useable
-
8/10/2019 220 Working With a Style Guide Within DITA
4/15
-
8/10/2019 220 Working With a Style Guide Within DITA
5/15
5
Three Ages of Tech Writing
Before computerisation ong- an
Demarcation of skills
Computerisation Word processors (WordPerfect, Word)
Desktop publishing (Ventura, PageMaker,
Modular XML-based
Methodologies (eg, DITA)
Influences on Tech Comms
Globalisation Embedded UA
Technical
Communication
Agile
Re-useDublin Core
o u ar y
Single-sourcing Facets
-
8/10/2019 220 Working With a Style Guide Within DITA
6/15
6
The Need for a DITA StyleGuide
What is a Style Manual?
A set of standards governing the design and.
Usually takes the form of a printed manual.
Originators: publishing organisations,standards bodies, government agencies andpublication departments
xamp es:AGPS Style Manual
Chicago Manual of Style
News Limited Style
-
8/10/2019 220 Working With a Style Guide Within DITA
7/15
7
Need for a DITA Style Manual
Style manuals promote consistency
Leading to authority
and readability
Existing Style Manuals focus on style-based authoring, and most are entirely
One of the difficulties of DITA adoption isworking without a relevant Style Manual
Style Guide Content vs Form
45%
55%
58%
42%
-
8/10/2019 220 Working With a Style Guide Within DITA
8/15
8
Style Guide Content vs Form
30%
70%
100%
Traditional Style Manual Use
-
8/10/2019 220 Working With a Style Guide Within DITA
9/15
9
DITA Style Manual Need
How style guides work
Document the standards and conventions used
Self-policed by authors themselves Example a style guide might stipulate that:
Each topic should have a primary heading thatdescribes the content of the topic.
DITA's language reference is a type of style
But many requirements can be policed by thevalidating editor For example, a topic cannot be saved unless it has a
title
-
8/10/2019 220 Working With a Style Guide Within DITA
10/15
10
Interchange
WOOO r e nce an nce n y
Company supplying components tomanufacturer should supply documentation
Component document consumed byassembly document
e es on e same app ca on o estandard
The DITA standard has gaps
DITA Style Manual
Supra-organisational semantic mark-up rules
mpor an w en e orma anguage ru esthemselves are open to interpretation or ?
or or ?
DITA Language Reference is large, technical,and impenetrable for non-technical technicalauthors
Example Stem sentence followed by a list
Authority (eventually) of Style Manual via opensource, community ownership
-
8/10/2019 220 Working With a Style Guide Within DITA
11/15
11
Examples
DITA Language Reference
The command () element isrequ re as e rs e emen ns e a. It provides the active voice
instruction to the user for completing thestep, and should not be more than onesentence. If the step needs additional
,element inside an element.
-
8/10/2019 220 Working With a Style Guide Within DITA
12/15
12
The DITA Style Guide
Short Description used throughout
What element for keystrokes?
The uicontrol element should be usedwhen describing keys on a keyboard, andthe userinput element for describingkeystrokes that the user must input.
More detailed explanation and toolneutral mark-up examples
The DITA Style Guide
What Element for Keystrokes?should be used to mark up keyboard keys, such asEnter, Ctrl and Backspace. The best approach is touse the uicontrol and userinput elements, dependingon context.
When describing keys on a computer keyboard, usethe uicontrol element. For example:< >Use the Tab to move from field
to field.
Note: Do not use the shortcut element; this element isintended to identify keyboard shortcuts indescriptions of user interface controls in windowedapplications.
-
8/10/2019 220 Working With a Style Guide Within DITA
13/15
-
8/10/2019 220 Working With a Style Guide Within DITA
14/15
14
Sudden, abrupt end
Questions, Discussion, Ideas
-
8/10/2019 220 Working With a Style Guide Within DITA
15/15
More information
www.ditastyle.com
www.scriptorium.com/books/the-dita-style-guide-best-practices-for-authors/