Editing in DITA

1
Editing in DITA

• Or how we attained enlightenment
• Michelle Carey and Shannon Rouiller

2
Topic-based information

• DITA provides the platform for topic-based, or
  article-based, information.
• Topics are self-contained chunks that float in an
  ocean of other topics.
• Of course, these topics are linked.
• Information architecture is a Web, not a linear
  book.

3
Information centers

• A collection of topics for one or more products.
• http//publib.boulder.ibm.com/infocenter/discover/
  v8r5m0/index.jsp

4
Best practices process

• One DITA person controls the CSS or XSLT
  overrides
• Editor or architect tells DITA person what to
  change.
• One person controls the content reference
  (conref) file.
• This file contains product names and other
  reusable content

5
Best practices process

• Do DITA code reviews.
• Editor and DITA guru review DITA topics from all
  writers.
• We review several topics of each type task,
  concept, reference, specializations.
• The code review ensures that everyone is tagging
  correctly and consistently.
• Do code reviews until you think every writer gets
  it right.

6
Best practices linking

• Too many or bad inline links.
• Inline linking often reveals topic architecture
  problems.
• Control linking through maps relationship tables
  (reltables), not inside topics.
• Less maintenance for writer
• More visible to next owner of the topic set

7
Best practices metadata

• Use metadata to control versioning, supported
  software, and so on.
• Why? Less maintenanceversions change every year
• You dont need to hard code versions or operating
  systems in many cases.

8
Best practices tagging

• Missing index entries
• Misuse of list types ol, ul, and dl
• Overuse of sections
• Too many sections often reveal topic architecture
  problems Is this an effective, self-contained
  topic?

9
Best practices tagging

• Task topics have the most problems.
• Incorrect task topic tagging
• uicontrol and userinput using incorrectly
• choicetable not using consistently
• Info overusing
• Indexterm not adding to the metadata (prolog)

10
Best practices short descriptions

• Probably the most difficult tag to write for.
• The shortdesc text must make sense in multiple
  contexts.
• Cant be a list lead-in
• Shouldnt just repeat the title
• Should be short
• Cant be self-referential
• At IBM, we created guidelines for shortdescs for
  various topic types because writers had such a
  difficult time writing effective short
  descriptions.

11
Shortdesc as first paragraph
12
Shortdesc as hover text for links
13
Shortdesc as text in child links
14
Shortdesc text in search engine results page
15
Discussion points

• What do you edit? DITA files, PDF, what? Do you
  edit in the files?
• Do you still edit books?
• How has editing changed with DITA?
• Architecture changes. More up-front organization
  editing. Less please edit my book.
• Editors must know the tags no more make this
  bold or why isnt this mono?
• More attention to structure and coverage, and
  less attention to low-level consistency and
  detail.
• What if DITA and guidelines clash?

16
Thats all folks