1 / 16

Editing in DITA

Editing in DITA. Or how we attained enlightenment Michelle Carey and Shannon Rouiller. 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.

nemo
Download Presentation

Editing in DITA

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  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 maintenance—versions change every year • You don’t 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. • Can’t be a list lead-in • Shouldn’t just repeat the title • Should be short • Can’t 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 isn’t this mono?” • More attention to structure and coverage, and less attention to low-level consistency and detail. • What if DITA and guidelines clash?

  16. That’s all folks…

More Related