DITA

Empower Your Team to Write with One Voice While Still Sounding Like Themselves

The Content Wrangler - Thu, 2018-11-01 17:00

The trouble with companies is that they’re full of people, and people insist on having separate personalities and distinct voices. So it’s no wonder that issues of consistency and tone of voice creep into our conversations when we take an honest look at our content.

In my Content Wrangler webinar Empower Your Team to Write with One Voice While Still Sounding Like Themselves delivered on Nov. 15, 2017, I discuss the role voice plays in unifying a company’s content strategy. I give suggestions for how you can build a brand voice without sacrificing the individuality of the content creators on your team—including a simple, fun exercise.

Read on for some highlights from my talk, including answers to these questions:

  • What does “voice” mean?
  • Why define your brand voice?
  • Who needs to use your brand voice?
  • How do you define your brand voice?
  • How can your writers still sound like themselves?

Or go to the webinar, and listen to the whole hour’s worth for free.

What does “voice” mean?

For a business as for a person, your voice (aka tone of voice) is how you sound, who you are, what you stand for, and how you interact with people as conveyed in language. When your voice is unmistakable, the way a personality is unmistakable, people recognize you not just by what you say but also by how you say it.

Elements of voice:

  • Word choice
  • Word order (syntax)
  • Sentence length
  • Punctuation
  • Metaphors

Basically, every choice you make with language—whether or not you make those choices intentionally—contributes your voice.

For example, if your brand voice is friendly, upbeat, and casual, you might use the occasional exclamation point. (I could do that right now!) If your voice is more formal, you would stick with periods.

When your company’s voice is distinct—that is, when everyone producing content for your brand is speaking with the same voice—your audience will say (as Ahava Leibtag said to Ann Handley last year in her Content Marketing World talk), “I read a piece of content of yours and within two sentences I know you wrote it.”

Indubitably.

Or… Cool.

Or… Damn cool!

(Would you say “damn” in your company’s customer-facing content? Would you use an exclamation point? If you don’t know, your company needs to define—or better communicate—its voice.)

Why define your brand voice?

You define a brand voice for several reasons:

  • It gives content creators more confidence.
  • It gives customers more consistency.
  • It gives the company more credibility.

Think of a brand that you love. That brand has some kind of voice that resonates for you. You see something from that brand, and you instantly have a connection to it as though it’s a friend. You have a sense of who is talking.

How can customers love you if YOU don’t know who you are?

Consequences of an undefined voice:

  • Confusion (internally and externally)
  • Brand erosion
  • Slower time to market
  • Costlier, less accurate translations

How do you quantify the benefits of defining a corporate voice? One way is to survey companies that are doing it. Acrolinx, for example, surveyed over 200 content professionals in companies that manage their terminology. (For their full report, see Terminology Management: How Companies Use the Words and Phrases That Matter Most to Their Business.) The top reasons respondents cited for managing terminology were “to ensure correct usage” and “to help enforce style and tone of voice guidelines.” And the top benefits they cited, as shown in this chart, were “more consistent brand voice” and “less confusion within tech docs due to inconsistencies.”

Who needs to use your brand voice?

All content creators in your company, including people creating presale and postsale content, need to use the same brand voice. In fact, the presale-postsale distinction is false. Some companies find that documentation brings in over 50 of their qualified leads. So documentation often IS sales literature.

In other words, all content that customers see needs to follow the corporate voice guidelines.

Why would you want to talk differently after the sale anyhow?

How do you define your brand voice?

You can define a brand voice however you like. Many companies choose a handful of adjectives, that is, describing words, such as “reliable,” “thorough,” outrageous,” and “funky” (not that you’d ever find those four words together in the same company’s voice description).

Avoid meaningless adjectives, such as “cutting-edge,” which are so overused as to be unhelpful. Some people call these cotton-candy adjectives because they’re full of air and lack substance.

Your voice adjectives aren’t meant to go in the content itself. They’re for internal reference; they support writers in making decisions about customer-facing content.

List your adjective in this-not-that pairs

One way to make your set of adjectives especially useful is to put adjective pairs in a this-not-that structure. This structure gives writers sort of bumpers. Limits. What to do—and what not to do.

Example from the Content Marketing Institute voice guidelines:

  • Authoritative but not pompous
  • Approachable but not wandering
  • Informative but not academic
  • Quick-witted and relatable but not corny
  • Entertaining but not inappropriate

Example from the MailChimp voice guidelines:

  • Fun but not silly
  • Confident but not cocky
  • Smart but not stodgy
  • Informal but not sloppy
  • Helpful but not overbearing
  • Expert but not bossy

Try sorting cards

Some companies, in defining their voice, find it helpful to use a deck of adjective cards, such as Margot Bloomstein’s BrandSort cards, to prompt conversation between stakeholders. One common approach is to sort the cards into three piles:

  • Who we are
  • Who we’re not
  • Who we’d like to be

The steps ideally go something like this:

  1. Pick a leader.
  2. Prepare a set of adjective cards.
  3. Gather stakeholders.
  4. Sort the cards. DEBATE!
  5. Document your choices.

This exercise’s value comes not simply in arriving at a final set of words but in having a rich debate, tussling over which adjectives fit or don’t fit your company, learning why your colleagues prefer certain words over others. A lot goes into a successful card sort of this kind. If you want to give it a try with your own team, check out my detailed write-up based on Margot’s methodology: Use This Simple (& Fun) Tool to Design Your Content Marketing Message Architecture.

How can your writers still sound like themselves?

After you’ve defined a brand voice, you’re ready to share them with your content creators. To supports writers in writing with one voice while still sounding like themselves, provide a combination of guidelines and examples.

Here’s a model from GatherContent (from their article A Simple Tool to Guide Tone of Voice):

This model includes four components, each shown in a circle: an adjective (“personality trait”) that describes your voice, one positive and one negative writing example, and the rationale for this choice.

Following this model, here’s what the writing guidance might look like (again borrowed from GatherContent):

Concrete how-to guidance like this gives a team of writers a sense of what everyone’s content should sound like without being overly restrictive.

Watch the full webinar

For the rest of what I had to say on this topic, watch the full webinar here.

The post Empower Your Team to Write with One Voice While Still Sounding Like Themselves appeared first on The Content Wrangler.

Categories: DITA

SPARQL full-text Wikipedia searching and Wikidata subclass inferencing

bobdc.blog - Sun, 2018-10-28 16:37
Wikipedia querying techniques inspired by a recent paper. Bob DuCharme http://www.snee.com/bobdc.blog
Categories: DITA

Gilbane Advisor 10-25-18 — flat world, infrastructure app cycle, digital archives

Internet, social, device growth flat in U.S. Certainly not news to suppliers of these technologies and services, and unsurprising to others. But this is just the kind of trend that is so obvious the reach of the repercussions can easily be overlooked. Any business that, even indirectly, depends on these products for growth, needs to assess how the saturation effects their product and […]

This post originally published on https://gilbane.com

Categories: DITA

Orbis to Showcase RSuite® and DocZone™ at 2018 Frankfurt Book Fair

Really Strategies - Thu, 2018-10-04 20:28
FBF 18 banner image

Annapolis, MD – Next week, the Orbis Technologies, Inc. team will make their annual journey to the Frankfurt Book Fair in Germany. New for 2018, both of Orbis’ CMS software products will be featured: RSuite and DocZone. The products will be presented side-by-side, as two distinct options for companies with publishing and content management needs.

Categories: DITA

Gilbane Advisor 9-26-18 — voice assistant use, blockchain martech, JS as CO2, disruption

The paradox of intelligent assistants Nielsen Norman tries to reconcile the poor usability of voice assistants with their high adoption rate. TL;DR users stick with the simple. Read More 22 blockchain-based martech companies you should know Obviously this is an early market, though with lots of activity. This article provides some good advice and a useful look at some […]

This post originally published on https://gilbane.com

Categories: DITA

Panic over "superhuman" AI

bobdc.blog - Sun, 2018-09-23 15:27
Robot overlords not on the way. Bob DuCharme http://www.snee.com/bobdc.blog
Categories: DITA

Tutorials for Static Site Generators on docslikecode.com

JustWriteClick - Sun, 2018-09-09 20:12

Sometimes treating docs as code seems overly complicated. Let’s break it into component parts – static site generators, development environments, source control, continuous integration, hosting, deployment, and testing docs. Yes there is a stack here to learn, but now you can take tutorials one-at-a-time no matter where you are in a docs-as-code exploration.

Go to docslikecode.com/learn to take a look!

With this new series of online tutorials I hope to provide a simplified view of static site generators plus the continuous configuration and deployment scenarios you can use for docs like code. The idea is to show the different “adventures” you can take through docs like code tooling. Then, there are also articles that help you evaluate each of three (yes, three!) static site generators – Hugo, Jekyll, and Sphinx.

Sphinx with Read the Docs

Sphinx screenshotSphinx with Alabaster theme on Readthedocs.org

This combination is a powerful one, and you can go completely through from setting up a GitHub repository with Sphinx for builds and RST as source, to connecting the repo by manually setting up the webhook so that it builds automatically to readthedocs.org. The theme is the Alabaster theme, as shown. With a simple change in the Sphinx configuration you can also use Markdown as source. This possible substitution shows the flexibility of any of these adventures.

Jekyll with GitHub Pages

Jekyll screenshotJekyll with Minimal Mistakes theme on GitHub Pages

For this opinionated walkthrough, you learn how to set up a GitHub repository with Jekyll and Markdown as source that uses GitHub Pages to automatically deploy the web pages to a web site. The theme is the Minimal Mistakes theme, which can be easily upgraded as the theme author continues to maintain the theme. Plus, you can deploy to GitHub Pages with a single configuration setting.

 

Hugo with Netlify

Hugo screenshotHugo with Learn theme on Netlify

If you’re interested in a Go-based workflow with no dependencies, you could go through the Hugo scenario. Set up a GitHub repository with Hugo and Markdown as source, then use Netlify to deploy a documentation site. The theme in place is the Learn theme, based on the Grav Learn theme.

 

I know there are many more combinations of build systems, testing possibilities, and static site generators and I welcome more tutorials! I know Asciidoc has another great build system that has another source type. We can also learn a lot about the templating engines in each system. Please submit a pull request if you have more ideas, and please use these tutorials for workshops or self-guided learning.

Categories: DITA

Orbis Awarded U.S. Patent for Ontology Harmonization and Mediation Systems and Methods

Really Strategies - Fri, 2018-09-07 20:37

(Annapolis, Md.) On August 14, 2018 Orbis Technologies, Inc. was awarded a U.S. Patent entitled, “Ontology Harmonization and Mediation Systems and Methods” (U. S. Patent No. 10,049,143 B2). The name of this award is the same as Orbis’ patent from November 22, 2016 (U. S. Patent No. 9,501,539), and they are similar in that they both cover aspects of query translations however, there are some major differences. This patent is focused on query translations and not on aspects of ontology mapping.  In addition, the patent emphasizes the ability of the ontology mediation and harmonization system to operate efficiently.  Queries that are compatible with a database ontology will not be translated, while queries that are not compatible with a database ontology will be translated.  The system seamlessly integrates the result sets returned from databases of different ontologies with result sets of the first ontology.

Categories: DITA

Update: Gilbane’s Digital Experience Conference in Washington DC

You may have heard about our Digital Experience conference taking place in Washington DC, April 29 – 30, followed by workshops on May 1, 2019. And if you’ve been a regular attendee at our Boston conference and are wondering why we are returning to DC, There is a reason, aside from the fact that late April […]

This post originally published on https://gilbane.com

Categories: DITA

Pipelining SPARQL queries in memory with the rdflib Python library

bobdc.blog - Mon, 2018-08-27 12:55
Using retrieved data to make more queries. Bob DuCharme http://www.snee.com/bobdc.blog
Categories: DITA

Global Marketing Insight: Don’t Translate, Transcreate!

The Content Wrangler - Thu, 2018-08-16 17:09

When developing content for multiple locales, in multiple languages, companies struggle with the idea of translation versus transcreation. Transcreation is about recreating the content in a language and style that connects with the consumer in a meaningful and emotional way. Professor Nitish Singh and Frank Hartkopf, Head of European Content, Axonn Media, explore the importance of transcreation to create content which truly hits the sweet spot of the local consumer.

This Global Marketing Insight video is provided by Brand2Global, the conference for global marketers, September 28-29, 2016 in Silicon Valley. Brand2Global Conference is an annual event designed for professionals who drive global marketing and are responsible for international market share and revenue. If you’re a global marketing practitioner, this is the conference for you. Learn more.

 

The post Global Marketing Insight: Don’t Translate, Transcreate! appeared first on The Content Wrangler.

Categories: DITA

Orbis to Present at Inaugural Army S&T Symposium in Washington, DC

Really Strategies - Wed, 2018-08-15 20:06
Army S&T

Annapolis, MD) Orbis Technologies, Inc. is proud to announce its selection as a presenting organization for the first Army Science & Technology Symposium and Showcase, taking place next week. The event will run from August 21-23 and will take place at the Walter E. Washington Convention Center in Washington, DC. Dr. Kojo Linder, Orbis’ Chief Scientist, will demonstrate “Multimedia Topic Modeling for Threat Actor Identification." Dr. Linder will discuss how machine learning can be exploited to prioritize multimedia artifacts (videos, images) found on social media for identifying threat actors.

Categories: DITA

Gilbane’s Digital Experience Conference call for speakers is now open

We love Boston, but it’s been awhile since we’ve had an event in DC and we miss it. We’ll be at the Renaissance Washington DC hotel with three especially relevant special events to partner with. The conference is April 29 – 30, 2019, followed by workshops on May 1. It may seem a long way […]

This post originally published on https://gilbane.com

Categories: DITA

Orbis Receives Visit from Congressman Anthony G. Brown (MD-04)

Really Strategies - Wed, 2018-07-25 16:00
1

Annapolis, MD) On Friday, July 20, Orbis Technologies, Inc. hosted Congressman Anthony Brown, representative for Maryland’s 4th Congressional District. Congressman Brown met with Orbis employees in a town hall style meeting and received a tour of Orbis facilities. 

Categories: DITA

Dividing and conquering SPARQL endpoint retrieval

bobdc.blog - Sun, 2018-07-22 15:52
With the VALUES keyword. Bob DuCharme http://www.snee.com/bobdc.blog
Categories: DITA

Every DITA topic should be able to fit anywhere. (Not really.)

Geekery - Sat, 2013-10-12 17:05

When I talk to writers about this, I state the case strongly: every topic should be able to fit anywhere. That always provokes some pushback, which is good. Of course it’s not really so, in practice. There are many combinations of topics that are just never going to happen. However, on a large scale, with hundreds or thousands of topics, there are many, many plausible combinations, some of them completely unexpected.

In fact, there are so many plausible combinations, you might as well not worry about the impossible ones. You might as well just go ahead and write each topic as if you had no idea what parent topic it was going to be pulled into.

That’s what we mean by “unleashing” your content with DITA. It’s the combinations of topics that bring the value, not the individual topics themselves. If you draft each individual topic so that it’s eligible for the largest possible number of combinations, you’ve multiplied the usefulness to the user (yes, and the ROI, and the technical efficiency) of the information in that topic. For any given topic, it’s true, there may be only three or four conceivable combinations in which it could make sense. For some, there might be hundreds. You’re not going to know unless you write for reuse in every case.

Once we’ve put this into action, we can go back to the managers and gurus and say, now you’ve really got ROI; now you’ve really got efficiency. Because we’ve given you something that is worth investing in, something that’s worth producing efficiently. Something that can delight readers with its usefulness and its elegance. This isn’t just content, this is writing.

Categories: DITA

DITA makes it possible for any information set, no matter how complex and huge, to be represented with a single page.

Geekery - Tue, 2013-10-08 00:33

In any information set, every component should be able to roll up into what is ultimately a single top-level summary. We know most readers don’t come in through the front door, but in principle you can provide the reader with an entry point that fully sums up what’s in the information set. From there they can drill down into more and more detailed levels. (Readers can be very easily trained to do this, because they have learned from their previous reading to scan for summary-like information and use that to judge whether it’s worth reading on for more detail.)

If each level is itself a rolled-up collection of subordinate units, and so on in turn down the ranks, what you are offering is a set of pages in which each page is itself a table of contents. The content is the navigation and the navigation is the content.

Picture this single page sitting at the apex of a pyramid. It contains (describes) everything that is included in that pyramid. Not that many people are ever going to actually read that page, but we need it to be there, because it defines the pyramid.

The bigger the pyramid, the higher level the information in its top node is going to be. So, for a very large information set, that single page is going to be very general. Each of its immediate child pages will be a level more detailed, and each successive level is going to be more detailed, until you get to the bottom “leaf” level where a topic describes only itself.

 

Categories: DITA

Modularity is what makes it fun to write with DITA.

Geekery - Tue, 2013-09-24 19:13

The most disorienting thing about learning structured writing is modularity. There are a lot of things we’ve learned about writing that we have to unlearn; this is the most fundamental of them. This is way bigger than deciding it’s OK to dangle a preposition.

Modularity means, in practice, conveying meaning in free-standing chunks instead of in a unified stream. Why is it so great to be free-standing? What does that get me, from a purely authoring perspective? (Remember, we’re still excluding managerial and technical perspectives from this conversation. You folks can come on back later.)

In mature DITA writing, many topics are built up automatically from component topics. Done well, these composite topics look like you lovingly handcrafted them with sections, section titles, section detail, overview material, and so on. In fact, you threw them together on the fly from component topics that you happened to have lying around.

How good your built-up topics are depends on how good those component topics are. How good the components are is largely a function of how well each one delivers meaning on its own, without having to wait for any other component to its job.

A composite topic that looks and reads like a composite topic is a failed composite topic. It needs to look and read like it was specifically conceived for this particular user at this particular moment. We want its component topics to match, in tone and style and scope, so well that they look like they were all written at once for this specific collection.

You’re working on a building, from the roof down and from the foundation up at the same time. You know what you need your built-up composite topic to do, which influences how to you’ll define and select or draft its component topics. At the same time, as your component topics come into being, they’ll influence the scope, scale and ultimately the effectiveness of the composite topic you’re building from them. In my experience, it’s when this process gets rolling that you really start to feel like you’re doing interesting, useful writing. This is where the fun starts.

Categories: DITA

Why is it that good writing feels like speech, but writing that’s transcribed from speech is usually bad writing?

Geekery - Thu, 2013-09-19 22:45

I’m reprising something I put up on this site about five years ago (lightly edited), because it still comes up in conversation occasionally and it’s fun stuff to talk about. Goes a little bit like this:

Writing has a tense, complicated relationship with speech. Good writing gives the illusion of resembling speech, or being derived from speech. But writing that is transcribed from speech is generally bad writing. It doesn’t feel like real speech. Some writing that does feel like real speech seems stilted when you read it out loud. The speech that writing evokes is imaginary speech, speech that takes place in your mind’s ear.

Often someone says something in a meeting that captures a thought perfectly. It may even seem elegant, like something that everyone knows but that hasn’t been expressed so well until now. Someone will say, “Get that down.” Later, at editing time, it turns out to make no sense at all. The context has changed, of course: what’s said in a meeting grows out of the experiences of everyone there, complete with unspoken assumptions, agreements and compromises. Text has little or no context. It appears out of nowhere, bearing all of its antecedents within itself. It has no hope of matching the immediacy of a spoken conversation. But we can rely on it to a degree that we can’t rely on our memory of speech.

Categories: DITA

DITA can transform our writing, but only if we take control of it as writers.

Geekery - Mon, 2013-09-16 15:51

Let’s leave aside, for now, the whole technical thing. Let’s separate creating content from building deliverables, at least abstractly. Let’s just talk about how we can use DITA to create beautiful, thrilling texts.

The first thing to acknowledge is that DITA is not just an XML-based way of producing the same kinds of products we used to push out with Framemaker. (That would be DocBook.) DITA is so much more than that. It’s a new way of writing. It invites us to look at our writing in a completely different way.

When people talk about DITA they almost always talk from one of two overlapping perspectives: the technical guru or the publication manager. Writers have reason to care about some of the same things those two care about, but neither focuses on what really matters to tech writers.

  • To the technician, DITA is mainly about all the awesomely efficient processing and automation you can do. To a writer, efficiency is great as a means to get good writing in front of readers. It’s not an end in itself.

  • What sells DITA to a manager is the cost savings from reuse and processing efficiency. Writers care about saving money too — to hire more writers with, of course — but investment only matters to us if it’s in pursuit of better content.

I suspect that’s why there are a lot of DITA-based help sites out there that aren’t really much better than the old paper or PDF or Winhelp or Dreamweaver products that they replaced. Gurus and managers have reconfigured their thinking, but writers haven’t. We’re still trying to write the kind of stuff we grew up writing, and trying to jam it into a new kind of container. But this new container demands a new kind of content.

Categories: DITA
XML.org Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | XML.org | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I