DITA

The RoundUp: Emojis, Voice Interfaces, Conversational Commerce, and Artificial Intelligence

The Content Wrangler - Tue, 2017-06-20 00:07

Welcome to The RoundUp, a curated quick peek at the best—and most interesting—news, views, and opinions about content on the web. Let us know what you think.

To have The RoundUp delivered directly to your inbox, subscribe today!

Example of new Google emojiEmoji Does It!

Google is notorious for having some of the worst emoji on the planet. Now it’s righting its wrongs–and taking on gender stereotypes, too. The effort aims to highlight the diversity of women’s careers and empower young girls.

In their popular podcastIt’s Nice That founders, Alex Bec and Will Hudson, discuss whether using emojis is a lazy alternative to the written word. Lazy or not, emoji are popping up in user interfaces and product documentation. Capitalizing on the ubiquity of ideograms, Sony Pictures will release the first animated movie about emoji this Summer. Patrick Stewart will play poop.

Meanwhile, the folks at Emojipedia rank the most popular emoji and track the recently updated Emoji 5.0 standard, which now includes new emojis from Unicode 10.0, as well as 183 emoji sequences used to represent gender and skin tone variants.

Want to create a custom emoji set? The Makemoji SDK allows you to craft your own.

Wordsmiths will appreciate this article, in which Matthew Kassell asks the question that is undoubtedly on your mind: “What Is the Plural of Emoji?”

Designing Content for Voice Interfaces

Voice is the new black—One day soon, we might talk to our devices the way we talk to our friends. Not in commands (like we do currently), but in conversational language. Our devices will talk back to us—and they’ll sound like people we want to speak to

Future voice interfaces will fundamentally change our relationship with technology and dramatically transform how we write content for customers. Perhaps that’s why IKEA wants to know, “Do You Speak Human?”

It’s definitely one reason our upcoming conferenceInformation Development World (November 28-30, 2017), will focus on helping you learn to craft dialog for chatbots and voice interfaces. Writing content for voice and chatbot interfaces will require us to develop new skills and ways of thinking about content. Visit the event website and sign up to be alerted when the roster of presenters goes live.

“Conversations are the new interface,” says artificial intelligence expert, Joe Armstrong. “Conversation designers are the new UX designers.” 

To help rid Alexa of its cyborgian cadence, Amazon recently upgraded its “speech synthesis markup language tags,” which developers use to code more human-sounding verbal patterns into Alexa.

The new tags allow Alexa to do things like whisper, pause, bleep out expletives, and vary the speed, volume, emphasis, and pitch of its speech. This means Alexa and other digital assistants might soon sound less robotic and more human. But, until then, you’ll need to speak to Alexa using commands she understands.

Enabling access to the web using the spoken word involves preparing content in compliance with several content standards, one of which is Speech Synthesis Markup Language (SSML).

Many people have conversations with machines on a daily basis. Most business, technical, and marketing writers, however, haven’t any experience writing conversational prose. That disconnect leads to conversations with less-than-stellar outcomes. Mary Jaksch offers ten tips for writing conversationally.

Understanding Artificial Intelligence

Computers do a lot for us these days and can sometimes seem intelligent like a person. But really, they’re more like calculators. Most only do what we program them to do and nothing more. But this is changing—and quickly—thanks to neurosynaptic chips and other advances in computing technology that enable machine learning.

Researchers are working on artificial intelligence which has the goal of making computers seem to be as intelligent as humans. Take a look at what’s possible today. Then, ask yourself, “How might artificial intelligence affect my job?”

Hanson Robotics provides a preview of the future with their most recent creation, Sophia. Watch her awaken. Artificial intelligence is no longer the stuff of science fiction. Today, it’s science fact.

That’s it for this week.

Got a content topic you’d like us to cover? Let us know!


April 26, 2017. Jimmy Fallon interviews Sophia. Learn more.

The post The RoundUp: Emojis, Voice Interfaces, Conversational Commerce, and Artificial Intelligence appeared first on The Content Wrangler.

Categories: DITA

Marketing Technology Bootcamp – Call for Speakers

The Marketing Technology Bootcamp is co-located with the Gilbane Digital Content Conference this year. Call for Speakers Deadline Fast Approaching The Call for Speakers deadline is fast approaching. If you would like to speak at the first annual Marketing Technology Boot Camp, co-located with the Gilbane Digital Content Conference May 28-29. Submit your proposal today. We […]

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

Categories: DITA

Gilbane Advisor 6-9-17 — news bundles, product managers, bad ads, kill AMP?

The trouble with news bundles “Tony Haile argues that the best way to put together a subscription bundle of news content is to guarantee readers an ad-free “experience” across a range of premium sites without access to all the content. That would eliminate the problem of slow-to-load pages. And it wouldn’t cannibalize single-site subscriptions.” Great […]

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

Categories: DITA

How Lucas Systems Integrated Swagger OpenAPI Definitions with API Explanations

JustWriteClick - Sat, 2017-06-10 13:34

Now available on docslikecode.com, this explanation of how to integrate Swagger with Swashbuckle for a REST API written with C#.

A Pirate’s Life for Me: Documenting APIs with Swagger

In it, Adam Locke, their lone tech writer, describes his troubleshooting process, the toolset including DapperDocs, OpenAPI, Nuget, Packet, and some clever code.

I appreciate reading about both the stop-and-start struggles and the clear wins found in this case study. Plus, it provides insights into how REST APIs can be written in any programming language. I have found it’s best to lean into the language your coworkers know best. Then you can get the collaboration gains offered by integrating the docs and code as tightly as possible.

Categories: DITA

Versions for docs sites with Jekyll

JustWriteClick - Tue, 2017-06-06 13:28

Versions of software product or a service need documentation sites to match those version numbers. As I investigated and learned more, I found layers of complexity when using a source control system to version the source documents while outputting a nice user experience with a static site generator such as Jekyll.

I have one possible solution to try out in this repo: https://github.com/justwriteclick/versions-jekyll/. Give it a try!

Categories: DITA

Speak at Gilbane – Apply by Friday June 2

Join us as a speaker, but hurry! We’re building the program for our annual Boston conference in the next few weeks and want to make sure you have the opportunity to apply to be a speaker. As a speaker you’ll be addressing our influential community of content management, digital marketing, and technology experts and practitioners. Join […]

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

Categories: DITA

Git and GitHub for Technical Documentation: Reviews

JustWriteClick - Mon, 2017-05-29 17:53

Writers might hesitate to work with others on content deliverables, and developers might feel they have little to contribute to the documentation. I assert is that no one can know everything, so distribute the workload by writing together just like you collaborate together on code.

What about reviews? How do you maintain quality while working on documentation in a code repository? Here are a couple of ideas.

If you have an active reviewer pool, one tip that sounds like an anti-pattern is to have your most active reviewers wait. Even if it’s only for a few hours, let the less experienced reviewers review first. Then have your more experienced reviewers review second. The less experienced reviewers learn if they missed some small detail or need to learn to step back to a wider context. These judgement lessons are difficult to teach without examples, so I suggest a wait.

Another tip that I really like but haven’t yet put into practice formally is to use a checklist. You could start with a fairly simple review checklist, such as:

  • Does the document build without errors? Automated testing sure helps with this checkbox!
  • Does the information belong where it is placed?
  • Does the change match the shared style guide?
  • Are the agreed-upon names and terms used correctly?
  • Do all the commands in the change work correctly? Here’s where automated testing also helps.
  • Does the commit message convey the purpose of the change?
  • Does the change claim to fix a doc bug, and if so, have you read the bug and agree with the proposed fix?

Sign up for a series of lessons on treating docs like code, and get a free PDF file of a review checklist for doc changes when using Git, GitHub, BitBucket, or GitLab, or any other source code system for your documentation.

Categories: DITA

The Power of Incrementalism in Content Marketing Strategy

The Content Wrangler - Thu, 2017-05-25 15:28

The demands of the digital landscape and a 21st-century audience are unforgiving. No one is searching Google for your advertisement. Most of the time, they aren’t searching for you nor for your company. More than likely, they are searching for an answer to a question. If you can provide a useful answer, they may peruse your website, social profile, and other content. They may not.

It takes more than a single piece of magnificent content to build an audience. Today’s viral post is tomorrow’s forgotten moment in time.

What’s the alternative to relying on big content “moments”?

Incremental Steps Lead to Big Wins

One superb piece of content doesn’t build a loyal audience. The art of incrementalism, changes by small degrees versus overnight leaps, builds an audience.

Content creators must establish cadence and rhythm. It may seem like a small first step, but it’s cadence that turns you into a media channel and publishing platform. Small steps ultimately build big wins.

There are very few successful online influencers because the incremental process takes patience and consistency. Influencers dominating specific niches didn’t pop up yesterday. They started methodically building an online brand many months—even years—ago, and now see the fruits of their labor.

This doesn’t mean delayed success. Each content creator has “wins” along the way. When a post resonates with readers, traffic spikes. But ownership of a space isn’t instant. That’s why the content process is an investment.

So, how do you establish a successful, long-term content marketing strategy incrementally?

Research and create content around one new keyword each week

Develop a firm understanding of who the influencers are in your niche. Who reigns supreme with certain topics and keywords? Who does your audience identify as a go-to resource? This research helps you identify new opportunities to increase your influence.

Start your week with Google Trends to find relevant topics and keywords. Do a quick Google search to see who ranks for those keyword concepts. Are these keyword topics saturated, or is there opportunity to stake a claim?

Look for a few new keyword themes weekly for your site, and select an idea for new content.

Measure success weekly

Building a kingdom takes time and determination. Monitoring and measuring content marketing results is essential to ensuring you invest time and effort into the topics and content types thst provide the most value.

At the end of each week, review your content analytics and compare this week’s performance with the last. If you don’t have software tools to help you, use a spreadsheet to analyze content metrics (views, engagement, shares, etc.). 

With weekly tracking, a picture of what your audience finds compelling will emerge. Push yourself to make today’s content as great as last week’s best performer. Review your progress again at week’s end; keep what’s working and ditch what isn’t.

These small, incremental adjustments over time will ultimately help you to refine your content marketing strategy.

Create a realistic content marketing (editorial) calendar

It’s important to plan your content marketing strategy around available resources. There’s no sense being everywhere at once if your team is a one-person show with only five hours per week to spend on content creation and distribution.

Instead, think contextually: “What can I create with my available resources to get the best return on investment?”  This may mean hiring an outside resource. It might mean getting creative on your own. Either way, it’s better to perform well on one platform—or master the creation of a single content type—than to have a subpar presence everywhere.

Discipline and Consistency Drive Results

Magnificent content creators understand discipline and consistency. If they promise to publish a newsletter every Monday morning, they do. If they tell their audience they will post new blogs on Tuesdays and Thursdays, they do. They train followers to visit routinely by becoming a media channel. Readers return because of the habit, the quality, and the consistency of the publisher.

To succeed in the world of digital content, your question shouldn’t be, “How do we create something mega popular?” The question is, “How can we sustainably create valuable content on a regular basis, for a long time?”

Take Incremental Steps

It’s OK to start small with content marketing. Make one promise to your audience, and execute on it. Once you have your Monday morning newsletter process down, make a second promise. Then a third. And a fourth. Eventually, you’ll have an entire digital marketing strategy.

Here are some quick wins to help significantly increase your output over time:

  1. Curate content by sharing relevant industry articles, videos, etc., so that you don’t always have to create content from scratch.
  2. Invite influencers and thought leaders to create guest posts for your website and social channels.
  3. Produce “Expert Roundup” blog posts that pool together advice on a specific topic from industry leaders.
  4. Create templates for quote graphics, infographics, list posts, etc., for productivity and efficiency. This way, you don’t have to start from scratch each time, and you can maintain brand consistency.
  5. Once you have enough content “in the hopper,” schedule it using tools like Hootsuite or HubSpot, so that you have more time to invest in other areas.

Remember, you can’t typically turn everything on at once. It’s far better to start small, build consistency with one or two types of content per week, and incrementally add a second, third, and forth over time.

About the Author:

Joe Griffin is the CEO of ClearVoice, a content marketing technology company for high-quality blogs and content destinations that he co-founded in 2013. He has served in executive roles at Web.com and iCrossing, and has founded multiple companies. You can follow his tweets @joegriffin or connect on LinkedIn.

The post The Power of Incrementalism in Content Marketing Strategy appeared first on The Content Wrangler.

Categories: DITA

Gilbane Advisor 5-19-17 — e-commerce, meta-platform, summarization and ML, design

E-commerce: What China reveals about the future of shopping China’s e-commerce market is the world’s largest and fastest growing. It is also more mobile and more integrated with relevant platforms than those in the West, allowing for smoother customer experiences. This goes beyond WeChat e-commerce capability, the envy of western messaging platforms. There are reasons […]

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

Categories: DITA

[May 31] DITA Summit: Best Practices and Lessons Learned From The Trenches

The Content Wrangler - Tue, 2017-05-09 19:56

4 DITA Webinars: Wednesday, May 31, 2017

Featuring Amber Swope, Jenifer Schlotfeldt, Rob Hanna, Keith Schengili-Roberts, Mark Lewis, Joe Gelb, Yehudit Lindblom

The Mini Virtual Summit on DITA Best Practices and Lessons Learned from the Trenches is a free, online educational event that provides strategies, tips, and lessons learned from technical communication practitioners.

The Summit (brought to you by Precision Content) features four presentations on issues impacting organizations that have adopted—or are planning to adopt—the Darwin Information Typing Architecture.

8:00am PT/ 11:00am ET

  • DITA Satisfaction Survey: Overcoming the BIG Challenges When Adopting DITA — Rob Hanna (Precision Content), Mark Lewis (Quark), and Keith Schengili-Roberts(IXIASOFT)—three content strategy experts with deep experience solving content conundrums with DITA, discuss the results of our 2017 DITA Satisfaction Survey. Our panel will review the top reasons survey respondents are dissatisfied with their DITA implementations. We’ll also discuss why some DITA projects fail and provide advice on how to best overcome these challenges (or avoid them altogether).

10:00am PT/ 1:00pm ET

  • DITA Best Practices: 10 Things You Can Do To Help Ensure Success — content strategy maven, Jennifer Schlotfeldt (IBM), highlights best practices to help ensure DITA project success. Jenifer will discuss ways to ensure the creation of effective topics, and how to properly architect content and assemble topics into information that is retrievable, organized, and reusable. She’ll also provide several “in the trenches” solutions for ensuring quality implementations, including guidance on content conversion.

Noon PT/ 3:00pm ET

  • Going DITA: Building an Implementation Plan for Positive Disruption — Joe Gelb (Zoomin Software) and Yehudit Lindblom (Suite Solutions) review a migration process that covers all the bases, helping you build your game plan for a winning DITA implementation.

2:00pm PT/ 5:00pm ET

  • It Takes A Village To Create Your Content Collection — Amber Swope (DITA Strategies) demystifies content collections and  helps attendees identify the requirements for a content collection, determine collection scope, and collaborate with stakeholders to build and maintain the collection.

Register today! It’s free.

Not sure you can attend? Register anyway. Attendees receive a link to the recording shortly after the event is over.

I hope to see you there, virtually speaking.

Scott Abel, The Content Wrangler

The post [May 31] DITA Summit: Best Practices and Lessons Learned From The Trenches appeared first on The Content Wrangler.

Categories: DITA

Gilbane Advisor 5-3-17 — SaaS era, Watson vs Einstein, e-commerce AI, FB monopoly

Why the SaaS era of journalism will be our most exciting yet During the first quarter century of the commercial internet, digital journalism has already gone through three eras: the portal years, the search years, and the social years. Each era advanced storytelling and presented new revenue streams, but I would argue that digital journalism […]

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

Categories: DITA

Uniting API documentation and code: InfoQ article

JustWriteClick - Wed, 2017-05-03 18:18

At the beginning of this year, I worked hard to summarize my thoughts on API documentation, continuous publishing, and technical accuracy for developer documentation. The result is an article on InfoQ.com, edited by Deepak Nadig, who also was forward-thinking in having me speak to a few teams at Intuit about API documentation coupled with code.

Always Be Publishing: Continuous Integration & Collaboration in Code Repositories for REST API Docs

Here are the key takeaways from the article.

Key Takeaways

  • API documentation provides a critical path for predicting customer success.
  • Collaborating on documentation close to the code provides better reviews of both the code and the document files, more automation efficiencies, and enables quality tests for documentation specifically.
  • Provide common documentation frameworks, standards, automation, and tools to give teams an efficiency boost.

If you have a story to tell about CI/CD for API docs, please send a Pull Request on GitHub to tell your story on http://docslikecode.com.

Categories: DITA

Gilbane Digital Content Conference 2017 – Call for Speakers

Content management, marketing, and digital experience How to submit a speaking proposal Review the conference and track descriptions below. Read the Speaker Guidelines. If you have questions not answered in the guidelines email us at speaking@gilbane.com. Don’t worry too much about which track you suggest for your proposal, unless it is for a post-conference workshop. And… Submit your speaking […]

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

Categories: DITA

The Wikidata data model and your SPARQL queries

bobdc.blog - Sun, 2017-04-23 13:43
Reference works to get you taking advantage of the fancy parts quickly. Bob DuCharme http://www.snee.com/bobdc.blog
Categories: DITA

How Balsamiq Solved Static Site Challenges with Code

JustWriteClick - Fri, 2017-04-21 11:58

Leon Barnard from Balsamiq wrote up a great series of challenges and solutions for the docslikecode.com website. His lessons learned are super helpful for all of us:

He summarizes the series best in his own words:

Static sites may seem to have more limitations than traditional CMSs or powerful technical writing tools. But if you can find a way around the limitations, you can reap the benefits that made static sites attractive in the first place. Markdown is easy. GitHub offers collaborative coding. A scripted robot can run a build command from a terminal. It’s writing excellent documentation that is tough. Fortunately, that’s what technical writers are good at. Having a developer liaison for the docs team can free writers from having to think about the limitations of the technology they’re using so they can focus on writing the docs.

Categories: DITA

Gilbane Advisor 4-18-17 — chatbots, nextgen IT, AR, marketing data, CX and distribution

What to do about the chatbot crisis It’s never been clear that messaging apps had a future as platforms. It is also a stretch to think of voice as a platform, at least in any general purpose sense. In either case it seems like a misuse of ‘platform’. Messaging and chat systems will continue to […]

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

Categories: DITA

RSI merges with Orbis Technologies, Inc.

Really Strategies - Tue, 2017-04-11 19:00
rsi-2016.gif

 Orbis Technologies, Inc. and RSI Content Solutions Merge to Form a Global Content  Management Software and Solutions Company

Categories: DITA

How Symantec Embedded a Tech Writer on a Developer Team

JustWriteClick - Thu, 2017-04-06 14:22

In this case study on docslikecode.com, Jennifer Rondeau shares her story of gaining the trust of her developer coworkers so that she could edit code comments for a remote management web service at Symantec. This is an excellent, in-depth piece, and I really appreciate her writing it up to share.

While Jennifer was writing up the story on GitHub and I was reviewing the case study, I asked her to clarify a couple of points she made about fully integrating with the development team. One was “Doc management was continually concerned that putting a writer into the code — writing code comments and code samples — would set developer expectations of the writers too high.” Ouch. She goes on to say that their root concern was about the extensibility of the model – they didn’t think it could scale across teams. While reviewing, she clarified to say that management didn’t want devs to think they could offload work that they ultimately were responsible for themselves, maintaining good code comments. Also, management found that the tech writers had much more code-savvy than originally thought, and the empathy and advocacy that writers could provide was well worth the risk in the embedded model.

Another point to clarify while drafting the case study was about doc build automation. In the end, they decided not to automate the doc builds as part of the code builds. I wanted to know: Was it a dev resources problem where doc builds were not prioritized high enough as compared to work on the services? Or, management didn’t want to invest the time? Or the writer didn’t find a way to do it herself? Or maybe the automation time savings wasn’t quite big enough for attention? She said, “Ultimately, the decision not to automate the Javadoc made sense — there are always pain points on either side of a decision like this.”

You can hear more from Jennifer in “Docs as Code: The Missing Manual,” co-presented with Margaret Eker at Write the Docs Europe 2016.

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