220 Working With a Style Guide Within DITA

8/10/2019 220 Working With a Style Guide Within DITA

1/15


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.


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


4/15


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


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


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/15

8

Style Guide Content vs Form

30%

70%

100%

Traditional Style Manual Use


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


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


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.


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.


13/15


14/15

14

Sudden, abrupt end

Questions, Discussion, Ideas


15/15

More information

www.ditastyle.com

www.scriptorium.com/books/the-dita-style-guide-best-practices-for-authors/

220 Working With a Style Guide Within DITA

Documents

Transcript of 220 Working With a Style Guide Within DITA