We discussed chapter 12: DITA Code Editing of DITA Best Practices at the February 15th meeting of the PDX DITA Book Club. Attendees included DITA enthusiasts from Wacom and NetApp.

Helping your team apply DITA consistently through code reviews

Code reviews are a great idea, especially when your team is first starting with DITA. Discussing different options and getting advice from your team means you will all learn faster. Josh had some great advice for teams implementing code reviews. He suggested agreeing on feedback rules before you start. It takes the focus off of what the writer is writing and places it on the rules you all want to follow.

The Common Problems lists at the end of the chapter are a great guide for people learning DITA. They can help people learn what to avoid and can be useful as a guide during code reviews. They can give you a place to start.

Figuring out where to start

Because that can be a real issue when teams first start with DITA. DITA gives you so many options. Which ones are right for your team?

The chapter recommends creating a DITA style guide for your team to follow, but it can be difficult to know which DITA elements you should use before you’ve even written one topic in DITA. Making some guidelines about what you’d like to use is a good idea, but your team should be very flexible in the beginning. As you write topics in DITA, the style guide should slowly create itself from what you’ve learned while actually working in it. The most important thing is to keep track of what you want to continue using and what you don’t!