Mastering Technical Communication Leadership

The Content Wrangler - Mon, 2016-12-05 22:20

Effective leadership is measured by customer satisfaction. Caring about your customers is crucial. Everyone is a customer: those who purchase and use your products, and your colleagues in every department.

Leadership requires a mixture of confidence and humility. Change doesn’t always happen quickly. Success may require all of the creativity, resourcefulness, and diplomacy you can muster.

Use these 7 Habits of Highly Effective Technical Communication Leaders to learn how to effectively put the customer first in all of your work. You can be an effective leader, regardless of your position.


While you may have less product knowledge than an engineer, you can view the product from a user’s perspective. Share your input and advocate for product and process improvements. Support similar efforts initiated by others. Focus on quality.


Process improvements can benefit everyone on the team, and improve product quality. Can the quality assurance team test the documentation? Can technical writers edit the user interface text and error messages? Can written documentation reviews become a factor in the performance evaluations of all product team members? Would documentation review meetings improve quality?


If you’re only writing the customer documentation, there is a chance that no one with your skills is editing other user-visible content. Even if you cannot edit this content, you can educate others about key technical writing practices. For example – One concept, One term – each word should be used to mean only one thing. This avoids user confusion, and saves translation funds. Another key technical writing practice: short sentences.


Think about how to create change – look before you leap. Understand the who, what, and how of change. Who are the key stakeholders and decision-makers, and what motivates them? What do they care about? How can you best bring them on board? What are their backgrounds – cultural, professional, educational? Start with curiosity. Listen. Discuss. Ask questions.


What do you know about the users – education levels, roles? How do they use the product and access the documentation? What percentage read the documentation in English? Collaborative efforts with other teams can aid your research. One way to learn more is to conduct a user survey. While gaining approval can be an uphill battle, the insights gained from a well-designed survey can make the effort worthwhile.


Not every organization needs to use the latest methodologies. What worked elsewhere may not work for your team. Bring others along with you – educate and involve engineers, quality assurance personnel, marketers, and product managers in assessing and exploring new methodologies. For example, some organizations can benefit from adopting topic-based authoring, without XML or DITA.


Mistakes provide tremendous opportunities for personal and organizational growth, including improved processes, communications, and skills. Accept these moments and make the most of them. Learn from successes and failures. Remember that what is truly irreplaceable is human life. Learn what you need, and what your coworkers need, to reduce and relieve stress.

Consistently practicing these 7 habits will support your development as an effective technical communications leader, continue process improvement in your organization, create harmonious work relationships, and improve content and product quality. Be the change you wish to see.

Want to learn about the key steps to success in technical writing outsourcing, how outsourced writers integrate into Agile teams, and how to manage these approaches to improve quality, save time, and reduce costs? Then check out this December 8, 2016 webinar held during The Content Wrangler’s Virtual Summit on Advanced Practices in Technical Communication.

The post Mastering Technical Communication Leadership appeared first on The Content Wrangler.

Categories: DITA

Content Potluck: Bringing Everyone to the Community Table

The Content Wrangler - Wed, 2016-11-30 21:25

Guest post by Niki Harrold and Laurel Nicholes

An increasing number of consumers no longer want to hear from one, authoritative voice. They don’t trust—or feel compelled to rely upon— your “official” communication channels. That’s because an increasing amount of your audience grew up online. They’re digital natives accustomed to digital content experiences. They want to feel connected to the content they consume and the brands with which they interact. They want content experiences that resonate with them; that adapt to the way they learn, live, and work.

In order to provide exceptional content experiences today, you’ll need to learn to share content in a social, community setting. To do so, you will likely need to expand the way you think about content and those who contribute it. This article explores the need for a new methodology we call Content Potluck—an approach we believe can help you craft engaging and valuable content experiences.

But, before we tackle the methodology, let’s answer this question: “How do you find the right content contributors?”

Team of creative professionals meeting in conference room

Finding The Right Content Contributors

The best content is content that addresses the needs of your audience; content that helps them solve a problem or answers a question. This content is often difficult to locate. Far too often, it’s buried deep within organizational silos. Finding it—and using it to improve customer experiences—is the goal.

Today, nearly everyone in your organization is a potential content contributor. If your firm is like most, chances are your co-workers are creating:

  • social media posts
  • blogs and articles on LinkedIn
  • answers to questions asked in community forums
  • instructions in email and text messages
  • how-to videos and other user assistance materials

Leveraging existing content assets creates a win-win situation for all. You gain access to valuable content. Your teammates get the chance to broaden their sphere of influence and grow new skills. And, your prospects and customers benefit from improved content experiences.

How do you find the right type of content contributor? Start by identifying the profile of an ideal content contributor (regardless of their function, title, or seniority in the company).

The Right Profile

Communities benefit from a wide variety of content creators. While diversity is important, content contributors should share some essential characteristics:

  • A passion for connecting with customers in a social forum, whether it’s your platform or online community, or public channels like Twitter, Facebook or GitHub.
  • A deep interest in improving how your customers experience your products and services. These folks want to learn from others as much as they want to share information.
  • Empathy for customer problems and a desire to provide solutions. Contributors who publish content—but don’t care to respond to queries—aren’t as valuable as those who interact with prospects and customers and engage them in conversation.
  • An understanding of the importance of social community and its potential impact on customer experience. Helping one person online can lead to the deflection of hundreds—perhaps thousands—of similar or identical support cases.
  • A desire for career advancement and personal development. Managing and participating in community content development efforts can lead to additional career opportunities. Frequently, junior team members see the importance of  such projects. They are often eager to dedicate time to such initiatives, in addition to performing their regular duties. They understand they are building a personal brand; an online reputation as a subject matter expert. They realize that their influence grows as their network expands.


Getting Them to the Table

So, how do you get others to contribute? How do you manage the potential chaos that may occur when you involve so many different voices? This is where Content Potluck comes into play.

Content Potluck is an approach designed to help you organize—and bring together—representatives from various content creation teams. Potlucks require an organizer (or two) to lead the initiative. Ideal organizers include community managers (who should already have relationships in place with other content producing departments) and technical writers and other content creators with deep product knowledge and an interest in broadening their skill set.

The next step is to schedule a recurring potluck—a gathering (preferably over lunch or breakfast) at which you will discuss:

  • Current content projects (by team)
  • Existing content types (being produced today)
  • New content types (to be produced in the future; derived from discussions with support staff, as well as from interactions in community forums)
  • Publication dates (to ensure the production of a steady stream of content)
  • Customer feedback from social media, communities, and content portals

Productive potlucks are facilitated sessions led by an organizer. To help your team focus on actionable outcomes, create an agenda and follow it. Nominate someone whose role will be to take notes for the group. Capturing tasks, deadlines, goals, and other meeting details—and sharing them with the team—is critical to success.

Invite members from all customer-facing content-producing teams. Interested participants can be found in nearly every department. Make sure to include content creators in marketing, documentation, support, training, engineering, product management, sales, professional services and beyond.

Next Steps

What do you do once you have your participants at the table, the discussion flowing, and notes captured? The next steps include identifying common tools, creating a universal editorial calendar, assigning action items, creating social media marketing campaigns to promote your content, and sustaining the group for long-term growth. Each of these subjects deserves its own blog post.

You can learn more about Content Potlucks—and find sample templates—here. Plan to attend our upcoming webinar during The Content Wrangler’s Virtual Summit on Advanced Practices in Technical Communication, December 7, 2016 at 3pm PT. You’ll hear real-life case studies and be able to ask questions of the presenters.


The post Content Potluck: Bringing Everyone to the Community Table appeared first on The Content Wrangler.

Categories: DITA

Pulling RDF out of MySQL

bobdc.blog - Sun, 2016-11-13 15:09
With a command line option and a very short stylesheet. Bob DuCharme http://www.snee.com/bobdc.blog
Categories: DITA

Learning the Vocabulary of GitHub for Docs

JustWriteClick - Sat, 2016-11-12 16:36

An article I wrote on GitHub for the docslikecode.com website:

What if you could use GitHub, static site generators, and Continuous Integration and Deployment (CI/CD) for our documentation? I imagine you can track your backlog and get some metrics on the quality with their nice contributor graphs. I bet you could measure “docs drift” to figure out just how behind the docs have gotten. Hey, let’s also get access to the developer playground and fun equipment! Let’s play on the slides and swings while we make cool and beautiful documentation, side-by-side as collaborators.

I hope you’re wondering, “What would happen if we treated docs like code?”

Believe me, your fellow software builders are wondering, experimenting, or already starting down this road. I’ve seen this vision come to life and want to share my experiences so more people can learn these techniques.


I’ve found that the principles inherent to the social web for coding work extremely well for documentation. The social web, leads to social coding, leads to social documentation.

What is GitHub?

GitHub Logo

Like many tools, git and GitHub were created by fire — through a pressing need for performant and efficient source control management for theLinux kernel. Read the history in the excellent Pro Git Book.

GitHub is the web interface for git the command-line tool, that works well on Linux, Mac, or Windows. To work with others on a project (code or docs), you merge files. This model is the opposite of using a “lock and checkout” model, where no one else can work on the piece at the same time as you. With GitHub, you can work separately and bring it all together later. Git has a non-linear branching model that can take some learning to get used to. That said, I’ve found git and GitHub for docs quite practical and even inspirational.

You can keep docs in a source code repository then the developers will review all your changes prior to merging them in. Unlike traditional source code management, branches are not full copies of entire code base so they are “cheap” and “fast.” The more Agile techniques are applied to documentation, the more treating docs like code makes sense.

GitHub definitions and parallels for information

I hope I’m talking to people who care a lot about words. Let’s start with some vocabulary and definitions to build upon.

  • Branch: Indicator of divergence from base without changing the main line (or “trunk” if you like to visualize organic tree-structures to remember this term).
  • Commit: Point in time snapshot of repository with changes.
  • Fork (noun): Copy of the repository that is entirely yours in your namespace. In GitHub-land, forking does not have a negative connotation that it can in other contexts (such as taking an open source project in a new direction in a huff to get different contributors). Rather, it is a way to contribute openly and publicly with your account attributed.
  • Fork (verb): Making a copy of the repository.
  • Issue: Defects, tasks, or feature requests.
  • Organization: Collection of group-owned repositories.
  • Pull Request: Comparison of edits to see if team wants to accept changes.
  • Push: Move changes branch-to-branch. The man page says “Update remote refs along with associated objects” but that’s more technical than we need here.
  • Repository: Collection of stored code or documentation that is written and built like code.
  • Review: Do a line-by-line comparison of a change, much like an editor would for documentation, and comment on improvements or changes.

These definitions can give you decision points to make about information architecture, so think about which deliverables you’ll make, who should review and collaborate on those deliverables, and how you can automate publishing with the chunks of a repository or an organization as overarching collections.

Take a look at this article’s source on GitHub to get a sense of the “source” for a document. We’ll look at the source aspects in a future article. To stay in touch, subscribe to get relevant emails in your inbox.

Categories: DITA

Fostering Innovation in Media and Publishing

The election is over—it’s time to look forward. In that spirit, I wanted to invite you to participate in a forum running right after Thanksgiving at the Gilbane Digital Content Conference this year—a town hall focused on innovation. Send suggestions via Twitter using #gilbane. Driven to change It’s no secret that publishers have been grappling […]

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

Categories: DITA

Gilbane Conference featured speakers

We are thrilled to have over 100 expert speakers for you to learn from and network with. Join us and your content and digital experience professional peers in Boston in three weeks. Below is a sample of who you’ll meet. Look forward to seeing you. Register today to save your seat – use code F16G for a […]

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

Categories: DITA

Gilbane Advisor 11-4-16 – mobile / desktop evolution, enterprise software, attribution

In the spirit of right-tool-for-the-job, our first two articles relate to the evolution of mobile and desktop platforms. There is a lot of, mostly rational, exuberance around the speed with which smartphones are taking over the world. But that is only possible because they are not limited to content in native apps and walled gardens. According to […]

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

Categories: DITA

The Economist and Pennwell – Innovating through Transformation

Join us in Boston in November for these featured case studies and our other 32 conference sessions. Innovating through Transformation How are media companies transforming their business from one reliant on content consumption to one in which content mixes with tools and / or community for greater engagement and new revenue? This session’s case studies […]

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

Categories: DITA

My SQL quick reference

bobdc.blog - Sun, 2016-10-30 15:49
Pun intended. Bob DuCharme http://www.snee.com/bobdc.blog
Categories: DITA

Markdown: Markup That’s Downright Simple

The Content Wrangler - Thu, 2016-10-27 20:52

Markdown Can Make Online Writing Easier Than HTML and other Markup Languages

Consumers crave technology—increasingly sophisticated tech—robust and loaded with useful bells and whistles. It’s why smartphones and streaming devices are such indispensable, in-demand gadgets today.

But as many electronic tools become more complex, others survive and thrive in a state of simplistic bliss—appealing to modern consumers with their retro charm and unfussy features. It’s this backlash against digital precociousness that helps explain the recent resurgence of vinyl LPs.

And it’s part of what’s behind the longevity and enduring popularity of a resource that bloggers, web writers and editors, developers, academics, technical writers, scientists, and even sites such as Reddit and GitHub continue to rely on: Markdown, a markup language created by John Gruber in 2004.

Dummy-Proof Text

Like other types of markup language, Markdown provides a simple means of adding additional information (tagging and metadata) to text so that it can be easily translated to HTML, XHTML, and other formats using built-in plain text formatting syntax. Markdown can be used with a simple text editor such as Windows’ Notepad or TextEdit for Macintosh, to create rich text, often with fewer formatting tags and keystrokes involved.

Carlos Evia, Ph.D., director of Professional and Technical Writing and associate professor of Technical Communication in the Department of English and Center for Human-Computer Interaction at Virginia Tech, Blacksburg, Va., says Markdown serves as an undemanding shorthand method for writing web content.

“In my work, I move in two professional environments: academic writing and technical writing. Markdown works as a plain text authoring tool for both of those environments and minimizes the need for complex applications or additional tags or markup. It bridges the processes of writing, say, on email or forums, and on web editors,” says Evia, who’s been working with plain text as his content creation platform of choice for many years. “Years ago, I started coding websites with HTML and then structuring documentation with XML, but Markdown allows me to use plain text for similar purposes. My Markdown files can become HTML and XML deliverables with one or two lines of commands or a few keystrokes.”

Simple By Design

Don Day, consultant with Austin, Texas-based Learning by Wrote, agrees that Markdown is less cumbersome than many other markup languages.

“Both markup- and Markdown-based authoring can be done in a simple text editor. But markup-based rules are inherently more verbose than Markdown, which relies on common textual patterns,” says Day. “For simple composition tasks, it is fairly easy to internalize the common Markdown conventions while writing a sequence of text in a simple text editor.”

To demonstrate the formatting straightforwardness of Markdown versus HTML, consider the following example.

“Say I am writing a task with steps giving my readers a recipe for making a birthday cake,” Evia says. “In HTML, a section with steps and sub-steps would look like the following:”



<li>Pre-heat oven to 350 degrees</li>

<li>Prepare cake sponge


<li>Combine sugar and butter</li>

<li>Beat in 3 eggs</li>

<li>Add vanilla</li>




“But in Markdown,” adds Evia, “all we need is the following:”

## Steps

  1. Pre-heat oven to 350 degrees
  2. Prepare cake sponge
  3. Combine sugar and butter
  4. Beat in 3 eggs
  5. Add vanilla

For a quick and helpful primer on using Markdown and many of its shortcuts, visit markdowntutorial.com.

Many popular and effective tools and extensions are available that improve upon Gruber’s original Markdown 1.0.1 text-to-HTML conversion tool (available for download here) via extra notation and scripts for processing. For instance, online content writers often prefer GitHub-Flavored Markdown Editor, authors who enjoy having a WYSIWYG-like experience commonly opt for editors like Mou that offer a built-in preview window, and many academic and technical writers gravitate to Pandoc.

“There are also many extensions now for popular content management systems that allow authoring with Markdown,” says Evia, who personally uses Atom or Sublime Text as his editor, allowing him to focus on the text before processing it with Pandoc or the DITA Markdown plugin developed by Jarno Elovirta.

One Size Does Not Fit All

Evia cautions, however, that Markdown isn’t a be-all-end-all tool, nor is it by any stretch a complete solution for many digital publishing needs.

“Markdown is for textual content. If an author is also in charge of graphic design, page layout, or multimodal content, then the Markdown text needs a second or even third layer of processing to be ready for end users,” says Evia. “Fortunately, there are many commercial and open source applications that take care of some of those steps, but there is frequently some heavy author work behind a final product that was built with pure Markdown.”

Some authors and developers actually enjoy the process of building through many layers, but others need to stick with desktop publishing tools or WYSIWYG (“what you see is what you get”) applications.

“These authors are used to the instant formatting gratification of a word processor or desktop publishing tool,” Evia adds.

Ultimately, Markdown is designed to be easy, and that’s the root of its advantages and disadvantages.

“Some authors will find its simplicity deceiving because Markdown text can need extra work to produce final deliverables,” Evia notes. “The language is pretty flexible and forgiving, so everyone can give it a try. However, it is not for everybody.”

The More Things Change The More They Stay The Same

Experts say Markdown endures because many programmers and developers inevitably forget a golden rule: KISS—keep it simple, stupid.

“Plain text will not go away,” says Evia, who believes Markdown will advance as younger generations continue to embrace it. “I see Markdown, or an evolution of it, being adopted by different industries to simplify content authoring, which is already happening.”

For companies, Markdown can be an especially useful and no-cost resource—provided all of the employees it is intended for are on the same page.

“The value of markup increases as organizations regard content as a business asset that can be reused and republished with fewer limitations and less rework as the needs of the business evolve,” says Day. “Settling on a single, strategic encoding makes sense from a business standpoint.”

However, if an enterprise opts for markup across the board, its authors may not agree from a usability standpoint.

“This tension between authoring interest and business interest is actually the most difficult business challenge I have run into in evaluating content recommendations for companies,” Day says.

The post Markdown: Markup That’s Downright Simple appeared first on The Content Wrangler.

Categories: DITA

Blockchain to Bots: a Look at Use Cases

Join us in Boston in November for this featured session and our other 32 conference sessions. Blockchain to Bots: a Look at Use Cases New technologies need use cases. First in theory to attract commercial investment, and second in practice to prove their worth. This session includes discussions on the potential of Blockchain for digital […]

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

Categories: DITA

Bots, Content, and Commerce

Join us in Boston in November for this featured session and our other 32 conference sessions. Here Come the Bots: How Innovations in Artificial Intelligence Will Shape the Future of Content and Commerce Today’s online transactions are still largely web-based despite the proliferation of smartphones and mobile apps. And these transactions are often part of […]

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

Categories: DITA

Gilbane Advisor 10-13-16 – Hive, WeChat, enterprise social, open images, marketing stacks

The Hive is the New Network This is a fascinating and thought-provoking read. To oversimplify enough to be obvious: The return on network scale is diminishing; future value will come from more purposeful, naturally emerging ecosystems that go beyond connecting and communicating. WeChat and Uber are examples, but there are also others and the details […]

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

Categories: DITA

RSuite Celebrates Ten Year Anniversary!

Really Strategies - Thu, 2016-10-13 17:16


Audubon, Pa.— October 13, 2016—RSuite is celebrating a decade serving the global publishing community’s automation needs to meet the increasing demands of a multi-channel and multi-device world. With thousands of users around the globe, RSuite has provided the automation tools necessary to reduce time to publication by over 50%. Powered by MarkLogic, RSuite continues to evolve to meet the enterprise publishing needs of Fortune 1000 businesses, government organizations, non-profit associations and standards bodies.

“When we launched RSuite over a decade ago, we knew we were at the forefront of something exciting,” stated Barry W. Bealer, President and CEO at RSI Content Solutions. “Today our success is measured in our client’s ability to completely transform their publishing environment by leveraging the enterprise class capabilities we have built in RSuite.”

“RSuite has been a pioneering product in the enterprise publishing marketplace. Built on MarkLogic, RSuite has enabled customers to leverage the MarkLogic database platform to manage content at scale” stated Matt Turner, Chief Technology Officer, Media and Entertainment at MarkLogic. “We congratulate RSI Content Solutions for 10 years of success with RSuite and look forward to the next 10 years of working together and helping customers integrate data from silos and maximize the value of their content and data.”  

About RSI Content Solutions

For over 16 years, RSI Content Solutions has been at the forefront of implementing content management solutions for publishers, media companies, Fortune 1000 businesses, government organizations, and more. With headquarters outside Philadelphia, PA, USA, an engineering center of excellence in Chennai, India, and affiliate offices around the world, RSI has helped over 250 global organizations implement appropriate content management solutions. For more information, please visit www.rsicms.com.

About RSuite®

RSuite has been built specifically for organizations that need to publish to multiple channels and to serve as their centralized publishing solution. RSuite is optimized for the creation, management, repurposing and multi-format, multi-channel delivery of content by utilizing an enterprise?strength of MarkLogic. In addition to its strong XML capabilities, RSuite manages any and all forms of digital assets (MS Word, PDF, images, audio, video, etc.) and all of its associated metadata.

RSuite’s powerful and highly-configurable workflow engine allows customers to implement multiple workflows that incorporate both manual and automated tasks, such as transformations, packaging, delivery, and more. Customers are implementing RSuite to manage the end-to-end publishing process, from content creation through multi-channel, multi-format deliveries. For more information, please visit www.rsuitecms.com.

Categories: DITA

Gilbane Conference Keynotes Announced

Conference: November 29 – 30 and Workshops: December 1 Boston Fairmont Copley Plaza Join the digital marketers, technologists, and analysts leading the thinking and doing — making modern digital content and customer experience strategies a reality. Register and save your seat today Keynote presentations Wednesday, November 29, 8:30 – 10:00am Keynote panel – Industry analysts Wednesday, November 29, 11:00 – 12:00pm Register today to save your […]

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

Categories: DITA

RSuiteUC16 Rewind

Really Strategies - Mon, 2016-10-03 12:30

THANK YOU to everyone who participated in this year’s RSuite User Conference and Tech Day.  By all accounts, it was a raging success!


Quotes from This Year’s Event:

  • “Your clients just like you so much…”
  • “I found the user panels and case studies engaging and thought-provoking…”
  • “Free headshots? Epically great idea…so much better than free swag!”
  • “Leslie…You and your stable system….”
  • “1.8 million docs exported in just a few hours…”
  • “One-click eBooks!”
  • “No click eBooks!”
  • “RSuite automation helps reduce external composition costs by 80% while speeding production up by 2 weeks.”
  • “Globalization through centralization…”
  • “The number of people who have hearts in their eyes for @lisabos at #RSuiteUC16 is staggering.”

Special Thanks

A special thanks to our great panelists:

And also to our sponsors:




Thanks again to everyone for making RSuiteUC16 so fantastic…we look forward to an even bigger and better event in 2017!

Categories: DITA

Introducing Docs Like Code

JustWriteClick - Tue, 2016-09-27 03:22

I recently tweeted about a side project called Docs Like Code and wanted to tell you about it here. It’s a specifically-focused site where I can share my best practices and lessons learned about applying software dev techniques and tools to software documentation. I want to learn and teach at the same time as I keep exploring this space.

If you want to see a bit of how the site is put together, and how you can use GitHub to make web sites, join in. I have an email list you can join to get information as the site grows.

#mc_embed_signup{background:#fff; clear:left; font:14px Helvetica,Arial,sans-serif; } /* Add your own MailChimp form style overrides in your site stylesheet or in this style block. We recommend moving this block and the preceding CSS link to the HEAD of your HTML file. */ Enter your email address to learn about docs like code together

In the meantime, take a look at this quick less-than-five-minute look at how you can build Jekyll sites locally.

Categories: DITA

Understanding Accessibility

The Content Wrangler - Mon, 2016-09-26 21:23

CW-Language-Cover-v4-front-smallThe following content originally appeared in the book, The Language of Content Strategy, a collaborative effort from 52 top content strategy practitioners, edited by Scott Abel, The Content Wrangler, and Rahel Anne Bailie, Chief Knowledge Officer at Scroll. The book, published by XML Press, is a collection of terms defined by contributors known for their depth of knowledge in that area of expertise. Each definition is accompanied by an essay that explains the importance of the term within the world of content strategy. This post, contributed by Char James-Tanny, is understanding accessibility.


Understanding accessibility: What is it?

Accessibility is the extent to which content is available, understandable, and usable by all, regardless of disabilities or impairments such as sensory, physical, cognitive, intellectual, or situational.

Why is it important?

Accessibility is a W3C Web standard and, in many countries, is the law. Accessible content is easier to use and maintain, more search-engine friendly, and increases usability and understanding.

Why does a content strategist need to understand accessibility?

One of the main tenets of communication is to know your audience, but this has not always been valued on web projects. When developers only tested sites in Internet Explorer on large monitors at small resolutions, their audiences suffered a less-than-stellar experience when using another browser, a mobile device, or larger fonts.

While you may want to create content that is available, understandable, and usable, the chances are good that you’re ignoring as much as 20% of your audience.

How can we make content more accessible to people with disabilities?

Accessibility happens during design, development, and delivery. Many content strategy best practices already address accessibility:

  • Use headings (with tags or styles, not manual formatting)
  • Use short sentences (fewer than 25 words) and short paragraphs (no more than three sentences)
  • Write in second person, active voice, and present tense
  • Use the best word, not the longest

Take these additional steps to create accessible formatting and markup:

  • Left-justify text for left-to-right languages and right-justify for right-to-left languages
  • Use the correct color contrast (3:1 for large text and 4.5:1 for other text and images)
  • Use relative font sizes
  • Restrict the number of font families to three
  • Size all images consistently
  • Make sure that online deliverables have full keyboard functionality
  • Add the alt attribute to images (unless they’re only decorative)
  • Add captions and transcripts to videos
  • Define the :focus pseudo-class in the cascading style sheet (CSS)

Addressing accessibility issues up front saves time and money

Creating accessible content starts with the initial design and continues through the development process. If you wait until the project is finished, it costs more. Roughly speaking, making a change during development costs $25 USD; during QA, $500 USD; after release, $15,000 USD.

Want to learn more about content strategy terms?

Buy a copy of The Language of Content Strategypart of The Content Wrangler Series of Content Strategy books from XML Press.

The post Understanding Accessibility appeared first on The Content Wrangler.

Categories: DITA

Understanding IP Addresses

The Content Wrangler - Mon, 2016-09-26 15:56

With a computer or other connected device, we can connect to billions of websites, apps and devices anywhere in the world with the click of a button. It works because, behind the scenes, everything on the internet uses the same set of rules that is known as a protocol. By understanding the basics of the protocol, we can see what makes the internet work.

Understanding How Addresses Work

You can send a letter to almost anyone in the world if you know a few basic things, like their house number, street, and city. And because you also have an address, they can write you back. That’s because most of the world uses the same rules for physical addresses. This is a kind of protocol.

The internet is no different. Instead of houses, the internet has billions of computers and devices. For information to get from one device to another using the internet, the device needs it’s own address. This is not a physical address, but an Internet Protocol address, or IP address.  IP addresses, like physical ones, link the whole network together.

Without IP addresses the internet could not function. They are essential. Unfortunately, because IP addresses are often hidden from view, we rarely hear or learn about them.

This video from our friends at CommonCraft reveals the powerful role they play on the web through a useful analogy involving traditional mail. It teaches:

  • Why rules or “protocols” are important in the basic functions of the web
  • Why traditional mailing addresses are an example of a protocol
  • How IP addresses are used to request and receive information on the web
  • Why there are two versions of IP addresses


The post Understanding IP Addresses appeared first on The Content Wrangler.

Categories: DITA

Semantic web semantics vs. vector embedding machine learning semantics

bobdc.blog - Sun, 2016-09-25 15:01
It's all semantics. Bob DuCharme http://www.snee.com/bobdc.blog
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