Structured Authoring WO DITA or Frame

1
Structured Authoring W/O DITA or Frame
2
Who Am I?

• Neil Perlin - Hyper/Word Services.
• In tech. comm. since 79 at DEC.
• Creating hypertext since 85.
• Creating WinHelp since 90.
• Using HTML since 91.
• Training/consulting on HATs since 95.
• XML, single-sourcing, mobile, structured
  authoring since 98.
• STCs lead W3C rep 02 05.

3

• Structured Authoring Today

4
Its Hot!

• Documents are
• Easier for authors to write consistently.
• Easier for readers to use.
• Easier and more predictable to single source.
• Easier to localize.
• All true for low-tech as well as high-tech.

5
Its Not Perfect, Of Course

• Problems include
• Some authors view structure as a constraint that
  limits their creativity.
• Requires more detailed up-front planning.
• Requires increased technical skill and rigor.
• Content ownership is often very political.

6
But On Balance

• The drawbacks are largely process-related and
  should be easily offset by the benefits.
• So lets get going!
• Just three questions
• What is structured authoring?
• In what context?
• What tool(s) should I use?

7

• What Is Structured Authoring? It Depends

8
In Frame or DITA Shops

• Frame or DITA shops often already have a
  definition of structured authoring.
• Frame offers structured Frame.
• DITA is, by definition, structured authoring.
• In both cases, structure is programmatically
  inherent in the material.

9
In Word or HATs Shops

• Its different in Word or HAT shops.
• Often less techie than Frame or DITA shops, no
  offense, so they lack the resources, skills, and
  culture needed for structured authoring.
• But structured authoring is the next big thing,
  and the rationale seems to make sense.
• But where to start?
• And there are far more Word and HAT shops

10
Flaws of Current Definitions

• People asking for definitions often hear that
  documents must be valid based on a DTD or XSD to
  be considered structured.
• What the !_at_ does this mean?
• It may be true, but isnt realistic for companies
  unfamiliar with the underlying technologies.

11
Flaws of Current Tool Referrals

• People asking about tools are often told
• Drop Word and switch to Frame.
• Drop Word and switch to DITA.
• Either one is usually unrealistic because of
• Lack of a compelling business case.
• Budget limitations.
• Corporate culture and politics.

12
So What To Do?

• Understand or learn the companys strategic
  direction, finances, culture, and politics.
• Stop laughing
• Consult with groups outside doc.
• Then pick the appropriate definition from the
  four that follow.

13
Definition 1

• Visually structured text in Normal style,
  formatted using the formatting toolbar.
• A silly example, but what many authors view as
  structured.
• A hurdle on the way to structured authoring.
• Content formatted this way can be manipulated a
  bit, using RoboHelps Word import parser.

14
Definition 2

• Programmatically structured using styles, perhaps
  a CSS.
• Better than 1 because it provides structure.
• Typically through the use of head styles.
• But the structure is up to the author, with no
  programmatic enforcement or locking.

15
Definition 3

• Programmatically and visually structured using
  templates with an attached CSS.
• Better than 2 because it makes it easier to add
  structure and corresponding styles.
• Entries in each template field automatically get
  the style assigned to that field.
• But the structure is still up to the author, with
  no programmatic enforcement or locking.

16
Definition 4

• Programmatically structured by being valid
  according to a DTD or XSD, like DITA.
• Clearly the best choice since it supports and
  enforces structure programmatically.
• But is it appropriate for you?
• Consider your culture and politics, intent for
  the information, and types of information, among
  other things.

17
Culture Issues

• Current mainstream tools Word/HATs dont
  support programmatic enforcement.
• Authors can largely do whatever they want.
• So youll need new tools, with the cost of
• Purchase, learning (with or w/o training), and
  lower productivity during ramp-up.
• Will your company support this?

18
Culture Issues

• The tools use unfamiliar technologies like XML,
  XSLT, DITA, etc.
• The same is true today what the ! is CSS, a
  template, a browser, etc?
• But the new tools call for more familiarity with
  the technologies in order to be used effectively.
• Youll have to become at least conceptually
  familiar with these technologies.
• Will your company support this?

19
Culture Issues

• The new environment requires greater rigor in
  development.
• Youll have to
• Enforce the use of style sheets, templates, and
  other standards.
• Do up-front analysis before starting a project.
• Follow defined workflows and processes.
• Will your company and its culture support this?

20
Culture Issues

• If you answer no to the prior three slides,
  youre not ready for definition 4.
• Now consider two political issues.

21
Political Issues

• Content ownership To correct old content and
  structure new content properly from the start,
  you need control over that content.
• Will its current owners give you that control?
• Tool politics If you switch from your current
  tool to Frame in a non-Frame shop, might this
  hurt the doc group politically?

22
Intent and Strategic Issues

• Intent are you creating
• Finished products Then code and structural
  cleanliness and consistency are irrelevant as
  long as the material displays correctly.
• You dont need definition 4, today
• Raw material Then code and structural
  cleanliness and consistency are crucial for
  controlled, predictable, automated processing.
• You need definition 4.

23
The Role of Tech Comm.

• Somebody has to do all this planning.
• Content strategy should be an extension of
  documentation strategy.
• Tech comm people are functionally the best people
  to deal with this.
• But are often marginalized due to technical,
  political, or perceived shortcomings.
• So what do we do?

24

• A Process for Moving to Structured Authoring

25
Strategize Big

• Identify or learn your companys product or
  service strategy as far out as possible.
• Stop laughing
• Identify how doc fits into that strategy.
• Be prepared for bemused or snide answers from
  people outside the doc group.
• Would the receptivity differ if documentation
  was retitled content?

26
Strategize Small

• Define a content strategy that supports the
  companys larger strategy.
• Define what youll need by way of
• Content types user guides, quick-refs, etc.
• Output variants based on audience, device, etc.
  e.g. single sourcing.
• Output formats WebHelp, HTML Help, etc.

27
Strategize Small

• Identify gaps in knowledge of technologies,
  methodologies, and internal standardization.
• Identify your intent for the content
• Finished products.
• Raw material to be re-used or localized?
• By what groups with what effect on structure,
  style, and wording?
• Identify whos supposed to be authoring.
• What do they think of the idea?

28
Strategize Small

• Identify your company culture controlling or
  loose and mission-oriented.
• Will structured authoring require change in that
  culture?
• How much control are you willing to lose?
• Ref. the DIGG riot.
• What legal exposure do you face?

29
Strategize Small

• Identify the information types you need and build
  templates, CSSs, and other supporting aids for
  authors to use.
• Disseminate these aids.
• Train authors on their use.
• Make use mandatory.
• Think about the future and plan to revisit the
  aids as needed.

30
Strategizing Summary

• You now have an idea what you want to do and can
  select a definition and tools.
• The more new features you want, the more new
  tools or tool updates youll need.
• Increasing costs in the short run.
• The more you want to distribute authoring, the
  more new tools and processes and reculturation
  youll need.
• Increasing costs in the short run.

31
Overall Summary

• You can now pick a definition of structured
  authoring appropriate for your company.
• Back up from 4 to find the definition thats the
  most future-proof with the least cost and
  disruption.
• Even if you cant go all-out today, you can start
  shifting your culture and thats a huge step
  forward.

32
Thank you... Questions? Hyper/Word
Services 978-657-5464 nperlin_at_concentric.net www.h
yperword.com
33
Hyper/Word Services Offers

• Training Consulting Development
• Flare RoboHelp RoboInfo
• Mimic Captivate
• XML
• Single sourcing Structured authoring