DITA code reviews

1. DITA code reviews Presenters: Megan Bock, Shannon Rouiller, Jenifer Schlotfeldt

2. Agenda • What is a code review? • Why do we do code reviews? • What do we find in code reviews? • Using a CSS to identify incorrect markup • What is the process for code review? • Tracking code reviews • Code review demo DITA Code Reviews

3. What is a code review? • It’s a learning process to fix coding errors early in the authoring process (or just after migration) • DITA source files are reviewed by a team (the author, a DITA advocate, and an editor) • Not a comprehensive review of every topic • 3-10 representative topics (concept, task, reference) • 30 minutes to 1 hour • Writer is expected to implement review comments throughout their topic set DITA Code Reviews

4. Why do we do code reviews? • To help each other learn correct DITA markup • To ensure consistent markup in your library, which results in: • Consistent output • Support for topic and map reuse • Simpler maintenance • Faster and smoother adoption of new tools and features • To identify possible requirements for DITA, our tooling, internal documentation, or our highlighting guidelines based on real usage DITA Code Reviews

5. What do we find in code reviews? • Element abuse • Unordered lists instead of parameter lists or definition lists • Visual elements (typically bold or italic) instead of semantic elements • Ordered or unordered lists instead of step markup (steps, substeps, and choices) • Code phrase and code block elements for random monospaced output • Pseudo-heads and pseudo-notes • Incorrect markup left by migration • Element neglect • Missing short descriptions • Scattered index entries • Incorrect structure of step content • Simulated menu cascades DITA Code Reviews

6. Semantic elements that are new in DITA • apiname – Use for API names such as a Java class name or method name. • wintitle – Use for title text that appears at the top of a window or dialog, and applies to wizard titles, wizard page titles, and pane titles. • menucascade – Use to document a series of menu choices, or to show any choice on a menu from which the user needs to choose. • note type – Use to expand on or call attention to a particular point. • term – Use to identify words that represent extended definitions or explanations. • shortdesc – Use to represent the purpose or theme of the topic. This information is displayed as a link preview and for searching. • Message markup (msgblock, msgnum, msgph) • Step markup (step info, result, example) DITA Code Reviews

7. findBadTags.css DITA Code Reviews

8. findBadTags.css DITA Code Reviews

9. Process example • Optional: Writer applies a special CSS (findBadTags) to check for improper tags (mostly highlighting). • Writer has the topics edited: • Writer submits a selection of topics to the editor for an edit. • Editor does a technical or copy edit and checks the output for obvious incorrect formatting and tagging. • Writer incorporates the edits and submits the revised topics for a code review. • The DITA advocate, editor, and writer meet, and the DITA advocate and editor review tagging and provide input to the writer about best practices. Comments are documented. DITA Code Reviews

10. How does the process vary? • Timing of code reviews: the earlier the better. • Voluntary code reviews vs. mandatory code reviews. • Informal vs. formal code reviews. • People in the code review: Whole writing team vs. just one writer. • Files to submit: DITA (including conref source files, DITA maps, and art files) and output files (for example, Eclipse plug-in). • Special CSS: (findBadTags) to check for improper tags (mostly highlighting). DITA Code Reviews

11. Ways to track code reviews Files Comments DITA Code Reviews

12. Ways to track code reviews (continued) DITA Code Reviews

13. Code Review Demo • Sample files DITA Code Reviews