Skip to main content
Opinion

The politics of DITA

Deciding on a content model is a critical step in many of our projects. Should it be DITA or something else? The answer, it seems, often has more to do with our client’s corporate culture than with actual technical requirements.

Read More
XML

Managing implementation of structured authoring


An updated version of this white paper is in Content Strategy 101. Read the entire book free online, or download the free EPUB edition.

Moving a desktop publishing–based workgroup into structured authoring requires authors to master new concepts, such as hierarchical content organization, information chunking with elements, and metadata labeling with attributes. In addition to these technical challenges, the implementation itself presents significant difficulties. This paper describes Scriptorium Publishing’s methodology for implementing structured authoring environments. This document is intended primarily as a roadmap for our clients, but it could be used as a starting point for any implementation.

Read More
Conferences

WritersUA: DITA pilot techniques

Mark Wallis of IBM ISS on how to run a successful DITA pilot. Some great information in this presentation on how to reduce risks.

He recommends selecting your pilot project based on the following items:

  • Right timeframe — don’t choose the project that has an imminent release
  • Choose a manageable documentation set size
  • Reduce risk by avoiding the strongest (or most critical) product
  • Identify a product with a known need to improve the user experience

They had one person out of a group of twelve, a “senior in name only” writer, leave because of this transition.

The ideal team for a pilot will need cross-functional and complementary skills:

  • Project management skills
  • Tools and technology strengths
  • Product knowledge and understanding
  • Architecture and design skills
  • Editor for standards and styles

Some advice on planning your content. (And it’s worth noting here that these apply to good writing and topic-oriented content rather than to DITA tools.)

  • No autopilot writing
  • Don’t just migrate existing content; you’ll get trapped in old paradigms (this assumes that existing content does not fit the DITA topic paradigm)
  • Perform use case analysis and task analysis
  • Determine the critical scenarios to document
  • Focus on tasks; backfill supporting information as needed

Some interesting discussion of “task support clusters,” which include conceptual overviews, related tasks, deep concept, and reference information. (Michael Hughes did a presentation on this earlier today, which I unfortunately was not able to attend.)

They set up a DITA War Room in a small conference room and met at least daily (1.5 to 2 hours per day. Yikes). They set weekly goals and used small tasks to build momentum.

There was also heavy use of an internal wiki to put up initial “straw man” design, then revise, comment, and discuss.

Layering deliverables
Implementation deliverables were split out into smaller tasks, such as:

  • Creating topic files, links, and navigation
  • Testing links from code and navigation
  • Creating task and reference topics
  • Validating help against the user interface
  • Creating concept topics for principles, guidelines, and best practices (“deep concept”)
  • Validating content in the expert community

For the third time, he points out that they are no longer documenting how to use a check box, so I guess I’ll mention it.

Choosing the DITA toolset

Task Modeler (free) for building and managing ditamaps, defining relationships between topics, and creating skeleton topics (stub files).

DITA-compliant editor to edit your topics.

Compiler (part of open source toolkit). Compiler? What are they compiling? HTML Help? Oh. He just referred to Ant as a compiler. Ohhhhhkay.

Proof of concept

They picked a subset of the pilot to do the proof of concept.

The presenter’s boss is quoted as saying, “There’s no such thing as bad weather, only insufficient clothing.” I’m guessing that she’s never been to Minnesota in winter.

The objectives for the proof of concept:

  • Learn and evaluate tools
  • Address technical obstacles
  • Specify end-to-end requirements

They learned that deliverable formats matter because they must deliver several different formats.

Managing costs

Purchase toolsets only for pilot team.

After completing proof of concept (successfully!), invest in tools for the remaining writers.

Wiki

They used their wiki to capture conventions and guidelines.

Improving acceptance

They paid attention to the change management issues. He doesn’t mention it here, but I would assume that the combination of an acquisition by IBM plus the requirement to change the authoring environment could have caused significant angst. Their approach included presentations, wiki content, email discussions, and online training.

At the point of transition, DITA boot camp was offered.

They used collaborative walkthroughs, or reviews, to help standardize their content development. Interesting. This sounds as though it could be a) threatening and b) an unbelievable time sink. But just maybe it might also c) help improve the content.

Other lessons learned

Think more, write less. (Don’t document the obvious, don’t document common user interface convention, write only if you’re really adding value.)

Don’t squander your ignorance. (If something makes you stumble in the interface, that will probably also cause problems for your users, so capture it.)

The more structured your content, the easier the transition to DITA.

Documenting the obvious teaches readers to ignore your text, so don’t document the obvious.

The handouts are available here: http://www.writersua.com/ohc/suppmatl/

Read More
Learning content Podcast Podcast transcript Taxonomy

Taxonomy: Simplify search, create consistency, and more (podcast, part 1)

Can your learners find critical content when they need it? How do you deliver personalized learning experiences at scale? A learning content taxonomy might be your solution! In part one of this two-part series, Gretyl Kinsey and Allison Beatty share what a taxonomy is, the nuances of taxonomies for learning content, and how a taxonomy supports improved learner experiences in self-paced e-learning environments, instructor-led training, and more.

Allison Beatty: I know we’ve made taxonomies through all sorts of different frames, whether it’s structuring learning content, or we’ve made product taxonomies. It’s really a very flexible and useful thing to be able to implement in your organization.

Gretyl Kinsey: And it not only helps with that user experience for things like learning objectives, but it can also help your learners find the right courses to take. If you have some information in your taxonomy that’s designed to narrow it down to a learner saying, “I need to learn about this specific subject.” And that could have several layers of hierarchy to it. It could also help your learners understand what to go back and review based on the learning objectives. It can help them make some decisions around how they need to take a course.

Read More
Structured content Webinar

Powering Conversational AI With Structured Content (webinar)

In this episode of our Let’s Talk ContentOps! webinar series, special guest Rahel Bailie, Content Solutions Director of Technically Write IT, and host Sarah O’Keefe, Founder & CEO of Scriptorium, discuss how organizations can leverage the unlikely connection between structured content and conversational AI.

In this webinar, attendees learn:

  • What is structured content, and how it fuels reliable conversational AI responses
  • How technical writers and conversation designers can collaborate for optimal output
  • Where to get started with structured content and conversational AI

Read More
Learning content Podcast Podcast transcript

Transform L&D experiences at scale with structured learning content

Ready to deliver consistent and personalized learning content at scale for your learners? In this episode of the Content Operations podcast, Alan Pringle and Bill Swallow share how structured content can transform your L&D content processes. They also address challenges and opportunities for creating structured learning content.

There are other people in the content creation world who have had problems with content duplication, having to copy from one platform or tool to another. But I will tell you, from what I have seen, the people in the learning development space have it the worst in that regard—the worst.

— Alan Pringle

Read More