Documentation Pipeline: The Awkward Teenage Years

Posted on August 1, 2019 by Marya DeVoto

At our August 14 meetup, we’re excited to hear from Josh Johnson of MapR Technologies, who will be speaking about “The Documentation Pipeline: The Awkward Teenage Years.” Josh is a DITA tools developer with 15+ years experience enabling tech doc and content management teams to provide state-of-the art content creation and delivery. Ask him your questions about how he’s supported doc teams in evolving their DITA implementations from simply up-and-running builds to highly efficient systems that support key performance goals.

The usuals are as usual:

Meetup from 6:30-8:00 PM Pacific Time on 8/14, with the talk beginning at 7:00
There will be food, and drinks in moderation!
The location is AppNexus/Xandr headquarters, in downtown Portland, OR at 711 SW Alder Street, 4th floor. The building is also known as the Alderway Building.
Please RSVP to marya.devoto@xandr.com if you plan to come in person–or if you’d like a call-in option. We always plan veg options, but can handle other requests with advance notice.

Hope to see you there!

Reviving PDX DITA – And a Meetup

Posted on February 11, 2019 by Marya DeVoto

This post is to announce we will be resuming quarterly meetings of our PDX DITA user group, which has been a bit sleepy the last couple of years. We’ll kick this effort off with a meetup for old and new DITA practitioners and friends on March 6th from 5:30-7:00 PM at AppNexus, 711 SW Alder Street, Portland. Bring yourself, your DITA-curious friends, and your opinions. We’ll talk about our current DITA successes and problems, and discuss ideas for future meetings. A more formal session will follow in April.

Many thanks to Puppet for hosting a number of meetings while the group didn’t have a home office. With my employer, AppNexus, beginning a big DITA migration, it seems like the perfect time to re-launch in a new location.

To review details:

March 6th, 2019, from 5:30-7.
AppNexus (a Xandr company)
711 SW Alder Street, Portland, Suite 400

As always, we’ll have snacks and drinks! Come say hi to old and new friends in that inimitable open-source way. Contact Marya at marya.devoto@xandr.com if you have questions.

Quarterly Meeting with Bonus Puppet Migration Talk

Posted on June 14, 2017 by Marya DeVoto

At our last meeting during the DITA Adoption Committee listening session, Puppet representatives shared some early details from their ongoing DITA migration project. During our meeting on the 28th of June, they’ll be presenting on “What We’re Learning: Midway Through Puppet’s DITA Migration.”

From Michelle Fredette, Puppet’s documentation manager:

Puppet writers talk about their migration from markdown files stored in GitHub and published to a static site, to DITA files managed in easyDITA and published to the company’s Drupal site. We’ll talk about the long slow march and decisions we’ve made to convert hundreds of files, design our architecture, train the team, and create a new publishing pipeline.

Food and chatter start at 5:45 at Puppet’s offices (308 SW 2nd Ave, Portland), with the presentation starting at 6:00. This will also be our quarterly meeting.

To RSVP, please email maryaed@gmail.com.

DITA TC Listening Session Report

Posted on April 2, 2017 by Marya DeVoto

On March 8, Amber Swope and Nancy Harrison of the DITA Adoption Technical Committee met with local DITA practitioners to listen to stories, suggestions, and complaints in reference to their individual journeys of DITA adoption. In attendance were representatives from FiServ, NetApp, Daimler, Viewpoint, and other local companies, and also Keith Schengili-Roberts, Scott Hudson, and Stan Doherty of the DATC.

The Technical Committee was particularly interested in gaps in the DITA specification that could be filled in for the next release. However, the discussion was wide-ranging, including the challenges of SME authoring in DITA, the need to constrain elements for new DITA writers to ease the learning curve, and the restructuring of existing content required before migration. We learned that the Lightweight DITA Committee is making progress on Markdown-to-DITA authoring; most attendees registered their recommendation for the Git flavor of Markdown as the most useful one.

If you missed this session and want to share your opinions, listening sessions will be ongoing, including one that will take place at the DITA North America conference in San Diego on April 25th. You can learn about more upcoming sessions as they’re scheduled at https://wiki.oasis-open.org/dita-adoption/listeningsessions.

February Book Club recap: DITA Code Editing

Posted on March 5, 2017 by Christy Lutz

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!

September Book Club recap: Converting Content to DITA

Posted on October 20, 2016 by Christy Lutz

We discussed chapter 11: Converting Content to DITA of DITA Best Practices at the September 28th meeting of the PDX DITA Book Club. Attendees included DITA enthusiasts from Jive Software, NetApp, Intel, and Viewpoint.

Some of the members had converted to DITA years ago and some of the members are doing it currently. We shared stories about implementing DITA and compared them to what we had read.

What was your company’s motivation for switching to DITA?

Lots of available tools
Open source architecture
Content reuse

How did you convert?
Most of the members converted to DITA manually by copy/pasting from their old tool into their new DITA tool. Leona particularly remembers a huge spreadsheet logging the progress of what was converted and what wasn’t.

Did you have to publish while converting?
None of our members had the space in their schedules to devote exclusively to migration. It was a gradual process of conversion, mostly scheduled between releases, with some writers on a team continuing to use an old tool while their teammates moved onto the new DITA tool.

Did you have a team devoted to conversion?
We all had a nice chuckle at the huge pilot team suggested in this chapter. Many of the members had little to no in-house DITA expertise when converting. As Marya noted, DITA is often aimed at large teams but is adopted by small teams, too. Those small teams are doing what they can, with whatever expertise they have and whatever training they can get.

What is the most important training you need while you are converting?

Topic types
Tagging
Maps
Folder organization

What are some good ways to get that training?

The “automatic” training you get by using a tool that validates against a DITA DTD is a great way to learn as you are converting, by warning you when you are doing something that DITA doesn’t allow.
Take a hint from “mob programming” and sit down with your co-workers to write some DITA topics as a team so you can discuss strategies and learn together.

Some things to remember while converting:

If you have a lot of topics in a fairly flat folder organization, you’ll need a good naming convention for your topics. Try keeping the name close to the title of the topic so you can find your topics more easily.
Converting HTML tables to DITA is time-consuming. If you are converting a lot of reference docs, make sure you allow time for it. If anyone has come across a solution that makes this easier, please let us know in the comments!
Start a book club of your own! You can learn so much by reading a beginner DITA book and discussing it with others in your DITA community.

Couldn’t make it to the meeting but have something to add? Want to share a story about your DITA conversion? Tell us in the comments!

More people are coming to every meeting! You should join us for the next PDX DITA Book Club meeting:
Where: Viewpoint, 1510 SE Water Avenue
When: October 26, 2016 from 5:00 to 6:00 pm
What: Chapter 12 of DITA Best Practices
RSVP: Email canncrochet@gmail.com

August PDX DITA Book Club recap: Content Reuse

Posted on September 18, 2016 by Christy Lutz

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: TBD
When: September 28, 2016 from 5:00 to 6:00 pm
What: Chapter 11 of DITA Best Practices
RSVP: Email canncrochet@gmail.com

Large-team DITA vs. Small-team DITA: A Friendly Face-Off

Posted on July 21, 2016 by Christy Lutz

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!

June PDX DITA Book Club recap: Metadata and Conditional Processing

Posted on July 21, 2016 by Christy Lutz

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, OR
When: August 24, 2016 from 5:00 to 6:00 pm
What: Chapter 10 of DITA Best Practices
RSVP: Email docs@jivesoftware.com

May PDX DITA Book Club recap: Short Descriptions

Posted on June 15, 2016 by Christy Lutz

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.

While it seems like there isn’t much we could add to the illuminating and in-depth presentation and blog post that Marya DeVoto did on short descriptions, here are some highlights from the meeting!

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, OR
When: June 22, 2016 from 5:00 to 6:00 pm
What: Chapter 8 and 9 of DITA Best Practices
RSVP: Email docs@jivesoftware.com