Category Archives: what we’re up to

Post navigation

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!

We discussed chapter 10: Content Reuse of DITA Best Practices at the August 24th meeting of the PDX DITA Book Club. Attendees included DITA enthusiasts from Jive Software, NetApp, Intel, Viewpoint, and DITA Strategies.

This chapter discussed the benefits of content reuse and single-sourcing as well as covering specifics of how you can do it with DITA. Our conversation on this chapter centered on how to think strategically about content reuse and DITA.

Conref source files
Our members have a bunch of great names for the topics that house content they plan to reuse in conrefs: master reuse files, conref libraries, warehouse topics. No matter what you call them, remember to set the processing-role attribute to resource-only and keep them in a place where you can find them easily.

Keys
Amber gave us a great overview of keys. Keys do for reuse what reltables do for links by storing information outside of topics, making it easier to find and update. Just like linking behavior is stored in reltables but resolve in topics, key values are defined in maps and resolve in topics.

Advice for content reuse
Make sure you always have a good reason why you want to reuse something. The ability to reuse is not a reason to reuse. When in doubt, don’t do it.

Start talking about content reuse strategy with your team, and keep talking about it. Amber suggested setting up brown bags where you and your team rewrite a topic together, talking about what to reuse and what not to. Josh has regular topic reviews with his team. I’m looking forward to scheduling something like it with my team soon.

Couldn’t make it to the meeting but have something to add? How does your team reuse content? Discuss in the comments!

More people are coming to every meeting! You should join us for the next PDX DITA Book Club meeting:Where: TBDWhen: September 28, 2016 from 5:00 to 6:00 pmWhat: Chapter 11 of DITA Best PracticesRSVP: Email canncrochet@gmail.com

After the monthly PDX DITA Book Club meeting on June 23rd, DITA enthusiasts met for the quarterly meeting to discuss using DITA in small teams versus in large teams.

Everyone took a turn talking about the benefits and challenges of their DITA teams. Most of our attendees work on small teams, but we still had great insights about life with large teams, too.

Let the friendly face-off begin!

Small-team DITA

Small teams are nimble and flexible and can respond to new information very quickly. Although there are less people to manage some important aspects of DITA, like content strategy, members of a small team get the opportunity to try a little of everything.

Small teams also get the chance to be problem solvers on a regular basis. On the other hand, if there is a problem, you are the one who needs to solve it. If you are on a small team (or a team of one), you may not have anyone to turn to with questions or for advice.

Small teams may not need a CMS…yet. Also, it might be more difficult for small teams to get resources, like a CMS. Kate’s team chose their company’s new flagship product for their first DITA project, to take advantage of the excitement around the new product to gain their company’s support for DITA.

Large-team DITA

Large teams often have enough people that different aspects of working with DITA can be delegated to different people. This may mean less diversity in the work that a member of large team performs.

Big teams need structure and policies, and they have enough people to provide that structure and make those policy decisions, such as which DITA elements to use and how to use them. But, with, large teams, these kind of decisions tend to be made at a slower pace.

It can be easier to onboard new writers in a large team because there are usually protocols already in place. In fact, Josh’s team has a help system just for their writers.

One of our members is finding out that, if your team grows because of acquisitions, you might find yourself with a large team made of a bunch of small teams. There might be a sweet spot for a DITA team, when your team is still small enough to be flexible and large enough to have considered DITA policies in place. What do you like best about being on a DITA team? Tell us in the comments!

We discussed chapter 8: Metadata and chapter 9: Conditional Processing of DITA Best Practices at the June 22nd meeting of the PDX DITA Book Club. Attendees included a new member from Viewpoint and DITA enthusiasts from Jive Software, NetApp, and Daimler.

These two chapters were a perfect pair to discuss together. Our group members had great tips for using metadata and conditional processing and plenty of examples of how they use them day-to-day.

If you have a long topic, instead of putting all of your <indexterm> elements in the <prolog>, you can put them nearer to the information that the index entry is describing to make that information easier to find.

Set the translate attribute to “no” for items that shouldn’t be translated or that will cause issues with translation services. Our members have used this for superscripts, part numbers, and button UI text that shouldn’t be translated.

Stan Rhodes made a great point about publication dates and the <prolog> element. It’s possible that the publication dates you use internally for a topic are not the same as the dates you want to use in your published topic. Consider whether the publication date you use in the <prolog> element is the one you want associated with your published topic.

Even though you can add conditional processing attributes to rel tables and inside topics, most of the group members preferred to add them to the <topicref>, if possible. It’s easier to find them and keep track of them that way.

We discussed whether or not any members dealt with condition sprawl, a term coined by the book writers to describe when a team has multiple conditions for the same purpose. We all agreed that condition sprawl would probably be more of a problem in large teams than in small teams, which was the perfect segue to PDX DITA quarterly meeting that followed!

Couldn’t make it to the meeting but have something to add? How does your team use metadata? Discuss in the comments!

More people are coming to every meeting! You should join us for the next PDX DITA Book Club meeting:Where: Jive Software, 915 SW Stark Street, Portland, ORWhen: August 24, 2016 from 5:00 to 6:00 pmWhat: Chapter 10 of DITA Best PracticesRSVP: Email docs@jivesoftware.com

We discussed Chapter 5:Short Descriptions of DITA Best Practices at the May 18th meeting of the PDX DITA Book Club. Attendees included DITA enthusiasts from Jive Software, NetApp, Daimler, and PSU’s Technical Writing program.

Personally, my favorite thing about short descriptions is the way they show up in mini-TOCs. I love being able to easily view a summary of the information in a set of topics. It helps me organize my information, and it helps readers know what to expect, too.

A helpful short description could make it so that an advanced user wouldn’t even have to read the topic.

To a similar point, sometimes the short description IS the whole topic, and that’s okay.

Short descriptions should be readable on their own. Avoid introducing lists in a short description, and refer to other topics by name instead of by “previous topic” or “next topic.”

Being consistent in applying short descriptions helps search results.

Some great final advice from Marya–if your topics are well-structured, your short descriptions should be easy to write. If you are having difficulty writing it, take a second look at your topic and make sure it contains only one point or task.

Couldn’t make it to the meeting but have something to add? What’s your favorite thing about short descriptions? Discuss in the comments!

More people are coming to every meeting! You should join us for the next PDX DITA Book Club meeting:Where: Jive Software, 915 SW Stark Street, Portland, ORWhen: June 22, 2016 from 5:00 to 6:00 pmWhat: Chapter 8 and 9 of DITA Best PracticesRSVP: Email docs@jivesoftware.com

We discussed Chapter 7:Linking of DITA Best Practices at the April 20th meeting of the PDX DITA Book Club. Attendees included DITA enthusiasts from Jive Software, ADP, Daimler, and PSU’s Technical Writing program.

Here are the highlights!

Inline links
We discussed how behavior influences inline links. Readers today are accustomed to inline links because of sites that use them heavily, like Wikipedia. Since readers have become somewhat immune to them, they are neither particularly disruptive nor do they appear that much more important than the surrounding text.

Still, we agreed that it is best to be selective when using inline links and to take advantage of the automatic ways you can create links with DITA, such as the sequence collection type. Toni’s team even implemented an “avoid inline links” policy.

Rel tables
Some of us use them; some of us don’t; and a few of us would like to try.
Advice for starting small with rel tables: They can be added to sub-ditamaps, as long as that sub-ditamap is above all of the links in your rel table. Putting rel tables at the sub-ditamap level also keeps them portable.

Collection types
The collection type we all thought would be the most useful (and some of us take advantage of) is sequence, especially for very long processes and wizards.

Scope attribute
The scope attribute on a link tells your .xslt where to look for the link. The peer attribute is useful when the topic you are linking to is not currently published, so the link will not break your build.

Couldn’t make it to the meeting but have something to add? Do you want to tell about your linking strategy or expound your love of rel tables (looking at you, Josh!)? Discuss in the comments!

More people are coming to every meeting! You should join us for the next PDX DITA Book Club meeting:Where: Jive Software, 915 SW Stark Street, Portland, ORWhen: May 18, 2016 from 5:00 to 6:00 pmWhat: Chapter 5 of DITA Best PracticesRSVP: Email docs@jivesoftware.com

Last night the PDX DITA faithful met to discuss recent noise about where DITA fits into a world where new developer-friendly tools are proliferating and gaining more functionality, and where some CMS vendors have been suggesting that CMS functionality makes DITA unnecessary and perhaps obsolete. To be fair, everyone at the table is working in DITA so we’re not free of bias, but it was interesting to talk about which use cases work for DITA and which don’t, and some of the reasons why other people don’t find DITA compelling.

A few themes emerged from the discussion:

–DITA has a lot of complexity and a big learning curve, but most of us have experienced the same problem with any tools as soon as the complexity and scale of projects increases. For a small project without a lot of content reuse, or multiple editions and versions in flight at once, or just a few writers, most tools do pretty well; when you start scaling up, you get into challenges and the workflows get less simple.

–It’s hard for people who don’t maintain information at scale and over time to understand how maintaining it can be as challenging and complex as maintaining code. Because most writing is ad hoc, created by non-specialists, and serves only one audience at a time, people who aren’t content or tech docs professionals are attracted to tools that present writing as text without apparatus. (A number of attendees had experience with showing someone in another job function the Oxygen XML editing interface and watching them recoil.)

–But those of us who are responsible for maintaining thousands of topics with overlapping content and producing and maintaining output for multiple audiences are kind of cynical about the value of hiding the complexity; it’s lurking underneath the covers anyway, since authors inevitably become responsible for the implicit context and future of what they write. (This is why I, personally, roll my eyes a little about the idea that DITA “frees writers up to just write”: as soon as you write something you’re making some tradeoffs about, for example, how audience-friendly versus future-proof and reusable it is. That means you probably have to know something about what’s going to happen to your text after you write it, whether you are yourself tagging any topic references or running filters against it, or not.)

—Tom Johnson alleged that developers don’t like XML and this led to a long digression about what developers will and won’t do when providing content, and whether this is any kind of blocker to developers’ creating documentation. There was some consensus that large repositories of developer-created content probably won’t end up being created in DITA (unless there is some kind of form-based interface intervening) but some attendees had had good experiences working with developers who wanted to single-source UI text and documentation text and saw XML as a logical choice for UIs to consume.

–Attendees had some useful responses to the allegations that a CCMS can replace DITA itself: when you do that, you’re back in the world of help authoring tools because insofar as the logic of the CCMS overrides the logic of DITA, you’re going to end up with functionality that is not portable once you take your content out of that CMS. For example, if you rely on the conditional processing of your CMS for filtered output, you will have to recreate that tagging in your DITA source if you start over in a different CMS. This creates the kinds of uncomfortable relationships with tool vendors that we have talked about before, where there is a cost to moving away from a tool, or you’re waiting on bug fixes to the tool to solve your problems. (I think I have that right. We use SVN and have never used a CMS.)

–There were many tacos. So many tacos.

As usual, it was a great and collegial discussion. Thanks to everyone who participated!

We had a larger group for our second installation of the PDX DITA Book Club on February 17th, including a student from the Masters of Science in Technical Writing program at Portland State University and DITA enthusiasts from Jive Software, Netapp, and Harmonic. We discussed chapters 3 and 4 of DITA Best Practices at this meeting.

Here are the highlights!

Chapter 3 reviewed concept topics and inspired conversations about what kind of topics we use the most (and what kind of topics we think we should use more):

We discussed using concept topics for information for beginners and targeting tasks to users with more experience. Beginners can be referred to concept topics for more information.

This led to one of the most interesting discussions from the evening, regarding how we refer those beginners to the concept topics that could help them. Even though it isn’t best practice, some of us admitted to adding cross-reference links directly in task steps or concept paragraphs, while some are big proponents of using <related-links>.

We discussed <sl>, <dl>, <ol>, and <term>, and the best uses for each. Most of us don’t tend to use <ol> but could see how it might be useful for workflows and rankings. We shared examples of when we used a <dl> instead of a <table> and why we decided on one over the other.

Chapter 4 reviewed reference topics (facts without explanations!):

We all use reference topics in different amounts, depending on our documentation needs. Some find references very useful for documenting UI, and others find less need for them.

We also discussed <properties> tables and <syntaxdiagram>.

Couldn’t make it to the meeting but have something to add? Do you want to weigh in on linking directly in steps or paragraphs versus using <related-links>? Discuss in the comments!

More people are coming to every meeting! You should join us for the next PDX DITA Book Club meeting:Where: Jive Software, 915 SW Stark Street, Portland, ORWhen: March 16, 2016 from 5:00 to 6:00 pmWhat: Chapter 6 of DITA Best PracticesRSVP: Email docs@jivesoftware.com

The PDX DITA Book Club is off to a great start! Five DITA enthusiasts from companies such as Jive Software and Netapp met for the first time on January 20th and discussed the first two chapters of DITA Best Practices.

We even grabbed a laptop and tested out a tag or two. Here are the highlights!

The first two chapters touched on tags, specifically task tags, which inspired conversation about how we use certain tags:

Info tag: There’s so much to say about the info tag! The biggest takeaway, though, is that it’s not cheating to wrap an info tag around a note tag to get a note to appear in a step.

Context vs. stepsection: Most of us use the context tag regularly but haven’t explored stepsection as much. We thought that it could be very useful to split up a long topic.

Importance attribute: We checked out the different values that you can apply to the importance attribute. Optional! Default! Deprecated! So many choices!

We also had some interesting discussions about how DITA influences the way we work:

Topic titles: The book counseled to make your titles meaningful, and we talked about how we do that every day. Basically, think, but don’t overthink. Be consistent when it makes sense to be, but be clear first.

Task analysis: Some of us had done task analyses at the beginning of large projects but, in general, couldn’t find a place for them in the daily workflow.

Task, concept, reference: We commiserated about starting to write a topic and changing the type halfway through.

Topic-based authoring: The book had a concise section on minimalist writing. We all strive for this all the time, so it was fascinating to take a step back and talk about it with fellow writers. We agreed that a single task should generally have 10 steps or less. It is better to split up a long process into multiple task topics that are tied together by a supertask parent topic than to overwhelm your reader with a long topic.

Couldn’t make it to the meeting but have something to add? Do you use the stepsection tag or the importance attribute? Do you do task analysis as part of your daily writing process? Discuss in the comments!

Even if you missed the first one, join us for the next PDX DITA Book Club meeting:Where: Jive Software, 915 SW Stark Street, Portland, ORWhen: February 17, 2016 from 5:00 to 6:00 pmWhat: Chapters 3 and 4 of DITA Best PracticesRSVP: Email docs@jivesoftware.com

We are looking to schedule future DITA Book Club meetings on the third Wednesday of every month. Information about future meetings will be posted on this website.

Please note, this meeting time will be reserved for discussing the latest two chapters in DITA Best Practices. If you have general questions and interest in DITA, please attend one of our regular quarterly meetings!