Adobe Workshop – TC Summer Camp 2017

Creating and Managing Content Across the Organization

Marketing, Engineering, and Technical Publications teams often develop content in different tools and store content in separate content management systems, which makes it difficult to share content and deliver a unified and consistent customer experience. Join Dustin Vaughn, Solutions Consulting Manager with Adobe, as he demonstrates a holistic approach to content and how it addresses many of the time-consuming and error prone aspects of content creation.

Session Details

Where: TC Summer Camp 2017

When: Saturday 9 September 2017

Workshop leader

Dustin Vaughn, Solutions Consulting Manager, Adobe

DustinVaughnDustin Vaughn is the Solutions Consulting Manager for the Technical Communication group at Adobe. He moved to Florida from Texas (days before he came to his first TC Camp), and enjoys taking his four sons to watch donkey basketball (It’s a real thing – check YouTube!). On the business side of things, he manages a team of experts in Adobe’s Technical Communication and eLearning products. Dustin has served as a panelist, speaker, and Adobe representative at various industry conferences. He designs, develops, and hosts technical, solution-oriented demonstrations for strategic global customers. He was also the solution designer and presenter for a cross-organizational and multi-product project designed for a key US Government client.


Session Notes

Scribe: Chris Niestepski

Top Takeaways:

  • Part of an Adobe Experience Manager (AEM) demo

Notes:

  • AEM is a web-based CMS (content management system/solution) geared toward building and deploying websites, mobile apps, and forms
  • Also addresses several long poles in TC tent: different authoring and graphics tools in different departments, collaborative review, translation, publishing to different platforms, file sharing, and version control
  • Although has deep integration with FrameMaker, does not require any particular authoring tool
  • XML Documentation Add-On includes a web-based DITA editor
  • Linked to multiple translation vendors (Translations.com, Linktext, MS Translator, Smartlink, etc.)
  • DITA mapper
  • List of files, file type, language, version, sync/update status
  • Example of filter use: select only DITA files marked out-of-sync and run update
  • Topic Summary section
  • Shows status at a glance: not started, in draft, ready for review, broken links, etc.
  • Baselines section
  • Similarly, shows file, type, version, date, whether or not file is the latest or is being worked on
  • Can keep old versions to reproduce a previous doc version in entirety (good for audits, legal)
  • Document assembly by drag-and-drop of text and image components onto placeholder boxes

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

Effective Collaboration Workshop – TC Summer Camp 2017

Use your unique strengths to engage content collaborators

Does this sound like you? You need to engage with diverse professionals and personalities on authoring technical documentation, but find it hard to work with people that generalize, jump to conclusions, make changes without reasons, and race the clock? You are not alone. 14% of knowledge workers had felt like striking a coworker in the past year but didn’t, and 87% of employees worldwide are not engaged at work.

The chances are that your colleagues are among them. You may even be disengaged yourself. How then, can we fuel our teams with energy, inspire colleagues for personal growth, and encourage peers to contribute to a cause much bigger than themselves?

To get there, you will need to do things differently. You will need to find new ways of applying your talents, move communication to a higher level, and narrowly focus on the commitments for which you provide the most value.

Learn that you can achieve such change. You can begin with yourself because most people around you are disengaged. Do not expect action from them.

But you know that you are different. You are aware that if you don’t take charge, very likely no one else will. You have that special gift and a personal conviction that your team needs – and you want to put it to work. You are ready to initiate change in yourself and your team.

You will gain a solid understanding of:

  • Why people act the way they do
  • Your four unique talents that benefit the team
  • Causes of stress in collaborative teams
  • The most value can provide to your commitments

You will leave with concrete action items that strengthen your relationships and significance with your project stakeholders and boss.

This TC Camp workshop will challenge you. At the core is advice on how to connect and communicate more powerfully with your team.

Participants have significantly increased their ability to implement new learnings by taking an optional Kolbe A Assessment before the workshop. While you will greatly benefit from the new insights that you will gain in these workshops, you will able to define better action plans for yourself when you use your individualized Kolbe A assessment.

Get the Kolbe A Assessment

Registrants can purchase a Kolbe A assessment at a discounted price in advance of the workshop. (Neither of us, TC Camp or Andrew, are profiting financially from your taking the assessment.)

Here’s link to get the assessment: https://www.warewithal.com/kolbeindexes/?name_id=781361showre&indexType=A&

Session Details

Where: TC Summer Camp 2017

When: Saturday 9 September 2017

Workshop Leader

Andrew Lawless, Rockant Inc

Andrew Lawless is a best-selling author, performance coach, educator, and consultant. He is razor sharply focused on inspiring and priming professionals for success. He uses a time-proven and scientifically verified approach to boost team performance. Andrew helps you uncover your strengths and hidden talents so that working together will be easier and more productive than ever before.

Andrew brings a unique blend of experience in behavioral sciences, publishing, localization, and education. He served as a trainer and consultant to the FBI’s Behavioral Science Unit where he helped analyze the mindset of hostage takers. Andrew presented his successes with improving global marketing teams to the US White House and testified before the US Senate on the importance of professional development in localization to the US economy. He is adjunct professor at the University of Maryland.


An Interview with Andrew Lawless

By Li-At Rathbun, the TC Camp Roving Reporter

Li-At: So this workshop is about effective collaboration. Why is the topic of effective collaboration—improving engagement with content collaborators—interesting to you?

Andrew: I’ve spent my entire life making good people better.

What gives me pleasure is not profits. That’s a business outcome, not a motivation. What motivates me is when I can look at a team or a person and see what I’ve inspired them to become, when they are fulfilled and have time for what matters most to them. That’s what excites me.

When I was in 6th grade, I got all Fs and was deemed “qualified only for special education school.” What happened was that I had developed juvenile diabetes and was nearly in a coma for 6 months. Nobody asked why I was suddenly failed in school and went from all As to all F. Instead teachers wanted to make sure that I will never have the ability to get a college degree. To this day, I am ambivalent about schools and its teachers. And at that time, I made the decision that no one that I can touch will have to go through that the way I did. Unfortunately, too many people at work feel misunderstood. Their potential remains untapped. These are the people that have my full attention.

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

Andrew: Most of my life—from childhood on—was all about how I can help good people get better. It breaks my heart when I go into organizations and I see people struggle. They struggle for 3 reasons:

  1. They have a way of working that clashes with somebody else’s.
  2. They have a set of natural strengths and their job doesn’t fit their strengths.
  3. Their boss requires a different set of natural strengths than that of the job holder.

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

Andrew: Everybody who works as a knowledge worker, needs to communicate with others, and wants to improve the quality of their communication.

People that went through previous workshops have called it a life-changing event. It’s very deep. I highly suggest that participants complete Kolbe A Index beforehand and come to the session with your results. I will introduce an exercise called the commitment clarifier – and your Kolbe A will be key tool to use it. That’s how you’ll get the most value out of the workshop.

[Editors note from Li-At:
Here’s link to get the assessment at cost: https://www.warewithal.com/kolbeindexes/?name_id=781361showre&indexType=A&.
Andrew is not profiting financially
from your taking this assessment.
]

In this workshop, I will:

  • Talk about your limiting beliefs.
  • Help you rewire your brain and turn limiting beliefs into empowering beliefs.
  • Help you understand the neuroscience and mechanics behind limiting beliefs.
  • Help you understand the framework, so that you can explain your own behavior and others’ behavior better.

Within these two hours—I will help you set the foundations for powerful change; to turn your limiting beliefs into empowering beliefs and actions. But that’s where it has to stop, because we only have a limited time.

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

Andrew: The most important thing is that technical documentation is increasingly becoming a collaborative effort that’s supported by technology (like GitHub—where you collaborate with developers), and we’ll also see more and more automation in terms of content reuse.

So if you want to continue to make a difference, it has to be on how do we work better as a team? How do we make a better product, or avoid things like having the terms in the screenshot be different than the terms in the document, or intermittent use of different terms for the same thing?

I’m also seeing that content authoring—tech doc writers—have a crucial position in R&D. Because they’re the ones, more than the developers, who can find the inconsistencies better than everyone else. And that’s such a crucial function and role.

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

Andrew: I hate camping. I can see why people are attracted to it. But my philosophy is that when I go on vacation, I want it to be better than at home.

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

Andrew: My wife, Ann. That’s the one person I would like to be with every single second of my life. She is my source of strength, my muse and inspiration. Sharp like a knife, steady like a train. I hate being away from her.


Session Notes

Scribe: Chris Niestepski

Top Takeaways:

  • Job stress not only can destroy one’s health but hampers teams and loses clients.
  • It’s the manager’s job to task and team his employees according to their natural strengths.
  • Employees, in turn, can greatly alleviate stress by accepting other’s strengths.

Notes:

  • Three sources of workplace stress:
  • Co-workers have different strengths/approaches
  • Job, or perception of it, does not match yours
  • Boss demands a different one than you have
  • Different skills in different brain areas:
  • Neocortex: cognitive skills, like knowledge, judgment; can be learned
  • Limbic system: affective skills, like motivation, values, desires; can be conditioned
  • Brain stem: conative “skills” like fight/flight and basic behavioral approaches; hardest to change
  • Negative behaviors like dwelling, gossip also come from primal fears of own failure or inadequacy.
  • Constant fear and fight/flight leads to long-term output of cortisol that’s disastrous for health.
  • In-born approaches can be changed but at great cost in mental energy.
  • Kolbe personality map has four conative types with three problem-solving behaviors:
  • Fact-finder: simplify, explain, specify
  • Follow-through: adapt, maintain, systematize
  • Quick Start: stabilize, modify, improvise
  • Implementer: imagine, restore, build
  • Most people combine all four types with one dominant behavior.
  • Opposites on map
  • have different approaches (systematic vs. impulsive, by-the-book vs. corner-cutting, etc.)
  • may complement with enough space, but are best not teamed directly together
  • What employees can do:
  • See conative opposites and different, not naturally wrong or unintelligent
  • Break away and exercise: body also shapes mind

Session Notes

Scribe: Carolyn Klinger

Stress (in this case work stress) is caused by working (or really clashing) with people with different strengths. Our limbic system, the center of emotion, reacts to this stress by creating cortisol, and this feeling spreads throughout the team. The limbic system can only feel. There is no language to express it. That’s why we need artists.

One of the biggest mistakes we make on collaborative teams is to assign tasks to the wrong people. We should not do everything together, completely collaboratively. Use one person’s talent to create the plan and ask another to look for ways to streamline it. Work independently even on a collaborative team.