Structured Authoring Workshop – TC Summer Camp 2017

Structured Authoring for Beginners

Are you new to structured authoring and topic-based writing? Are you more comfortable with unstructured desktop publishing applications and apprehensive about moving to XML or some other structured authoring environment?

This workshop is for you if you want to know the how, why, and what it is about structured authoring that has other companies pursuing something like DITA, even if, right now, you don’t have to do it yourself.

Get the basics of structured authoring and topic based writing in this gentle, but experiential workshop.

Session Details

Where: TC Summer Camp 2017

When: Saturday 9 September 2017

Get the slides

Workshop leader:

Janice Summers, Single-Sourcing Solutions, specializes in helping people who’ve only ever used unstructured desktop publishing applications learn structured authoring. She’s been successfully transitioning Word users to XML authoring for the last 15 years and hasn’t lost anyone yet!


An Interview with Janice by Li-At, our roving Camp Reporter

Li-At: So this workshop is about Structure Authoring. Why is Structured Authoring interesting to you?

Janice: Structured authoring forces us to think in terms that are a little different, a little more modularized. It makes it so our content stands on its own and it can be reused.

In traditional writing forms, we hodge-podge things together—like processes and steps together with descriptions and narratives—because we’re just thinking about a long-running document. But with modular writing, we separate the process (steps in a process) from the narrative. So that in some applications, we might insert this process step into a different type of content. Maybe we’re doing a troubleshooting guide, a users manual, and a general encyclopedia about the product. If we’re using a narrative form of authoring and not thinking in terms of structured authoring, everything’s mixed together and we have to reauthor for these different pieces. But if we think in terms of modularity and reuse, then we’re able to reuse that section in all these different publications—without having to reauthor it. Because we’ve done it once and we’ve done it well.

So I find it interesting because it forces us to step back and think a little differently, which I think is a good thing. I think it’s a little cleaner and easier. It’s difficult, yet easier. It’s difficult to recondition and retrain our habits. But once you get through that retraining and you start to think differently, it’s quite refreshing.

Nobody likes to write things over and over again. If you’ve already done it once, wouldn’t you rather work on something new and interesting?

Li-At: If this is a difference question, what attracted you to Structured Authoring?

Janice: The most attractive aspect of structured authoring is the ability to reuse. It should be the most attractive aspect for everybody.

I’m lazy; I don’t want to write it over and over again. I want to write it once and reuse it.  Then I want to work on something different. If I’ve got X number of hours in a day, I don’t want to be doing the same thing over and over again. I find no security and comfort in that. I’m selfish; I’d rather have more free time.

So I guess I find structured authoring really appealing because it’s going to save me time and drastically reduce the redundancy in my daily life.

Li-At: Who should attend this September 9 workshop?

Janice: This workshop is for anyone who’s curious about structured authoring. I tend to be quite unconventional when I do sessions. I like to really have engagement with people, and one of the best parts of TC Camp is that its intimate size provides a rare opportunity for candid conversations.

Aside from what I’ll teach, I’m hoping we’ll also have some interesting conversations about structure—what it means for each person who attends.

Li-At: What’s the one thing that all technical communicators should understand about Structured Authoring?

Janice: Structured authoring doesn’t mean DITA.

DITA is fantastic as an architectural design—it’s like a Rubik’s Cube. But you don’t have to be in DITA to think and act like a structured author.

Li-At: Okay, this is TC Camp. So my next question is, what’s your favorite camping spot?

Janice: Mount Madonna. It’s up in the Santa Cruz, California, mountain range and it has redwoods and madrone. Madrone is a shrubby tree that grows indigenous in redwood forests. It has this twisty, turny kind of way of growing in all different contortions because it reaches for the light in the dense forest.

Li-At: If you could take one person camping with you, who would that be and why?

Janice: Roger, my boyfriend. If I go camping without him, he’d be mad.


Session Notes

Scribe: Chris Niestepski

Top Takeaways:

  • “Structured” refers to writing in XML modules assembled and published downstream
  • Writers focus on writing, not formatting
  • Allows easier content sharing and updating across multiple docs
  • Enforces consistency, currency, and saves time and money, esp. with long docs

Notes:

  • Unstructured/typical authoring:
  • Top (outline)-down: usually sequential, almost always working in final doc (Word, InDesign)
  • Advantages:
  • Almost everyone has Word
  • Great for short to mid-size, single-author/use docs with few revisions
  • Disadvantages:
  • Formatting, notes, references, etc. all distract from writing
  • Redundant rewriting of similar sections for different docs
  • Not updating all docs leads to outdated content
  • Style differences between multiple authors
  • Word not built for long docs: formatting, internal refs break down
  • Structured authoring:
  • Bottom-up: written in chunks saved as XML modules, similar to HTML
  • Modules later assembled into docs, formatting left to pubs department
  • Advantages in time and cost:
  • Writers focus on writing
  • Common sections written, updated once for multiple docs and pub formats
    (derivative versions for instructor/student, different languages, etc.)
  • Easier to maintain consistent corporate style/tone and user experience
  • More future-proof if formats, branding, authoring tools change
  • Challenges:
  • Changes in writing/pubs mindset
  • Less familiar, often pricier tools (XML editors, FrameMaker, Flare, etc.)
  • CMS with tighter version control and traceability than SharePoint
  • Getting engineers or marketing to use it (solution: fill-in forms that generate XML output)
  • XML (Extensible Markup Language)
  • SGML = Standard General Markup Language, ISO standard for docs; some 3000 tags!
  • HTML = browser-standard subset of SGML
  • XML = SGML core-essentials allowing custom tags (<name>, <address>, etc.)
  • Modules must be well-formed (order, hierarchy, consistency) and pass XML validator
  • Example: Title, Short Description, Summary, Overview (<H1>, <P>, <P>, <P>)
  • DITA (Darwin Information Typing Architecture) a standard, ultimate form of structured authoring
  • Hierarchy: Type, Title, Description, Prolog, Body
  • Content types: concept, task, or reference
  • Includes book map for document assembly
  • Q: What is so special about Arbortext?
  • A: Its wide adoption by the defense industry as essentially the first major structured authoring tool.

Session Notes

Scribe: Allison Gisinger

What is structured authoring?

  • Topic based writing
  • Unstructured authoring is linear
  • You need to use a content management system (CMS)
  • Markup = tags that come before content that gives instructions for how to treat the content

Why do it?

  • Saves time and reduces cost.
    • Update in one place and it updates everywhere
  • Consistency
  • Centralized and Automated
    • because it uses CMS
  • Future Proofing your content
    • the syntax is timeless. Readable by any tool that can read native XML.
    • Changing the brand/style can be done by changing the style sheet
  • Commenting is a part of structured – makes it easier for editor and peer review
  • The authoring engine puts the content together. You just write and don’t worry about formatting
  • Allows for multichannel output – PDF and webpage

The Language of Structure

  • Style sheets – CSS is web oriented; there are other tools that are made for multichannel authoring

XML borm from SGML

  • SGML is usually for PDFs
  • XML works for multichannel

Well formed vs. Valid XML

  • Valid – architecture you are using. You can have something that is well-formed, but not valid. DITA is an example of valid

Simple Sample

  • Word Perfect used to be prolific, but now you wouldn’t be able to open those files unless you have Word Perfect.
  • XML is human-readable so it is future-proofed, unlike Word Perfect.
  • Word can even do XML, but if you open it up in notepad, it adds a lot of gobbledy gook

Sample 2

  • As long as you tag your sections, your style sheet will know what to do with it.
  • You’re HTML can be XML compliant and you can open it in either HTML or XML, as long as you use good form

Questions

  • Does structured authoring work for manufacturing procedures? DITA has a place, and companies need to determine if DITA is right or wrong. Structured authoring and modularizing your content is applicable everywhere.

What about Structure?

  • It takes a while for people to not have to hit publish all the time to see what their content will look like. That is one of the hardest things about moving to structured.

The Magic of Modules

  • Legal disclaimers – if you have a legal disclaimer in all documents and legal tells you to change it, you have to update it in each document. If it is modular, you only need to update it in one place and it will be updated everywhere
  • CMS can request the document in real time. When you update the module, it will be updated the next time that content is requested

What’s a Module?

  • Lasagna is traditional authoring – it needs to be built in layers
  • Salad is modular authoring. Just put a bunch of ingredients together and you have a salad. If you add or change an ingredient, you change the type of salad, such as a Taco salad.

DITA

  • Topic Type – there is basically 3 types (Concept, Task, Reference), but they all follow the same rule of having Type, Title, Description, Prolog, Body.
  • Task is a  “how-to” and the rules are rigid. Don’t confuse a task with a concept
  • You can have images within a task, but a table would be a reference. It would be pulled into the task in the final output.

Is it DITA? Does it matter?

  • When you choose a tool, get a “prenup” and know how you can get out of that tool if you want to change. Is it possible to export your content if you want a “divorce.”
  • MailChimp example – not sure if they use DITA, but it looks like DITA – Concept, concept, task. She can tell shtey reuse content and use the same structure for every task.

Questions

  • DITA Map = you have to make a recipe and pull things together for that recipe. Toast, Tuna Melts, grilled cheese, eggs benedict. We have written our steps on how to make toast. We have written ingredient lists, we have written concepts on each recipe. If I want to map together the recipe book, we will pull together all of this content. Ex: Title: eggs benedict, Reference your content
    • easyDITA.com – explains DITA
      • Your maps link your content together.
      • You have a centralized location for all of your content, then you create maps to pull it together.
      • MadCap Flare does something like this with Table of Contents. Usually your customer can see TOC, but they wouldn’t be able to see DITA maps
  • Common pitfalls for migrating – There is always something hard about migrating. On the back end of that, you will be rewarded. It is easier to get it into XML, then work on it from there
    • Conformance is required in DITA and it is uncompromising