160 likes | 290 Views
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.
E N D
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. • Of course, these topics are linked. • Information architecture is a Web, not a linear book.
Information centers • A collection of topics for one or more products. • http://publib.boulder.ibm.com/infocenter/discover/v8r5m0/index.jsp
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
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.
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
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.
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?
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)
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.
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?