Technology

A Guide to JES3 to JES2 Migration

IBM Redbooks Site - Wed, 08/15/2018 - 09:30
Redbook, published: Wed, 15 Aug 2018

This IBM® Redbooks® publication provides information to help clients that have JES3 and want to migrate to JES2.

Categories: Technology

IBM Power System E980 Technical Overview and Introduction

IBM Redbooks Site - Mon, 08/06/2018 - 09:30
Draft Redpaper, last updated: Mon, 6 Aug 2018

This IBM® Redpaper™ publication gives a broad understanding of a new architecture of the IBM Power System E980 server that support IBM AIX®, IBM i, and Linux operating systems.

Categories: Technology

IBM Power System E950 Technical Overview and Introduction

IBM Redbooks Site - Mon, 08/06/2018 - 09:30
Draft Redpaper, last updated: Mon, 6 Aug 2018

This IBM® Redpaper™ publication gives a broad understanding of a new architecture of the IBM Power System E950 server that support IBM AIX®, and Linux operating systems.

Categories: Technology

IBM Power Systems H922 and H924 Technical Overview and Introduction

IBM Redbooks Site - Wed, 08/01/2018 - 09:30
Redpaper, published: Wed, 1 Aug 2018

This IBM® Redpaper™ publication is a comprehensive guide that covers the IBM Power System H924 (9223-42H), and IBM Power System H922 (9223-22H) servers that support memory-intensive workloads such as SAP HANA, and deliver superior price/performance for mission-critical applications in IBM AIX®, IBM i, and Linux operating systems.

Categories: Technology

IBM Power System L922 Technical Overview and Introduction

IBM Redbooks Site - Tue, 07/31/2018 - 09:30
Redpaper, published: Tue, 31 Jul 2018

This IBM® Redpaper™ publication is a comprehensive guide covering the IBM Power System L922 (9008-22L) server, which was designed for data-intensive workloads such as databases and analytics in the Linux operating system.

Categories: Technology

IBM Spectrum Scale Immutability Introduction, Configuration Guidance, and Use Cases

IBM Redbooks Site - Mon, 07/30/2018 - 09:30
Redpaper, published: Mon, 30 Jul 2018

This IBM Redpaper™ publication introduces the IBM Spectrum Scale immutability function.

Categories: Technology

Machine Learning with Business Rules on IBM Z: Acting on Your Insights

IBM Redbooks Site - Fri, 07/27/2018 - 09:30
Redpaper, published: Fri, 27 Jul 2018

This Redpaper introduces the integration between two IBM products that you might like to consider when implementing a modern agile solution on your Z systems.

Categories: Technology

IBM Z Integration Guide for the Hybrid Cloud and API Economy

IBM Redbooks Site - Fri, 07/27/2018 - 09:30
Redpaper, published: Fri, 27 Jul 2018

Today, organizations are responding to market demands and regulatory requirements faster than ever by extending their applications and data to new digital applications.

Categories: Technology

Introduction to IBM Common Data Provider for z Systems

IBM Redbooks Site - Thu, 07/26/2018 - 09:30
Redpaper, published: Thu, 26 Jul 2018

IBM Common Data Provider for z Systems collects, filters, and formats IT operational data in near real-time and provides that data to target analytics solutions.

Categories: Technology

IBM Power Systems S922, S914, and S924 Technical Overview and Introduction

IBM Redbooks Site - Thu, 07/26/2018 - 09:30
Redpaper, published: Thu, 26 Jul 2018

This IBM® Redpaper™ publication is a comprehensive guide that covers the IBM Power System S922 (9009-22A), IBM Power System S914 (9009-41A), and IBM Power System S924 (9009-42A) servers that support IBM AIX®, IBM i, and Linux operating systems.

Categories: Technology

Building a SAN-less Private Cloud with IBM PowerVM and IBM PowerVC

IBM Redbooks Site - Tue, 07/24/2018 - 09:30
Redpaper, published: Tue, 24 Jul 2018

This IBM® Redpaper™ publication describes a software-defined infrastructure (SDI) solution with IBM PowerVC.

Categories: Technology

IBM Power System AC922 Technical Overview and Introduction

IBM Redbooks Site - Mon, 07/23/2018 - 09:30
Redpaper, published: Mon, 23 Jul 2018

This IBM® Redpaper™ publication is a comprehensive guide that covers the IBM Power System AC922 server (8335-GTH and 8335-GTX models).

Categories: Technology

IBM Software-Defined Storage Guide

IBM Redbooks Site - Sat, 07/21/2018 - 09:30
Redpaper, published: Sat, 21 Jul 2018

Today, new business models in the marketplace coexist with traditional ones and their well-established IT architectures.

Categories: Technology

Webmentions: Enabling Better Communication on the Internet

A list Apart development site - Thu, 07/19/2018 - 09:00

Over 1 million Webmentions will have been sent across the internet since the specification was made a full Recommendation by the W3C—the standards body that guides the direction of the web—in early January 2017. That number is rising rapidly, and in the last few weeks I’ve seen a growing volume of chatter on social media and the blogosphere about these new “mentions” and the people implementing them.

So what are Webmentions and why should we care?

While the technical specification published by the W3C may seem incomprehensible to most, it’s actually a straightforward and extremely useful concept with a relatively simple implementation. Webmentions help to break down some of the artificial walls being built within the internet and so help create a more open and decentralized web. There is also an expanding list of major web platforms already supporting Webmentions either natively or with easy-to-use plugins (more on this later).

Put simply, Webmention is a (now) standardized protocol that enables one website address (URL) to notify another website address that the former contains a reference to the latter. It also allows the latter to verify the authenticity of the reference and include its own corresponding reference in a reciprocal way. In order to understand what a big step forward this is, a little history is needed.

The rise of @mentions

By now most people are familiar with the ubiquitous use of the “@” symbol in front of a username, which originated on Twitter and became known as @mentions and @replies (read “at mentions” and “at replies”). For the vast majority, this is the way that one user communicates with other users on the platform, and over the past decade these @mentions, with their corresponding notification to the receiver, have become a relatively standard way of communicating on the internet.

Tweet from Wiz Khalifa

Many other services also use this type of internal notification to indicate to other users that they have been referenced directly or tagged in a post or photograph. Facebook allows it, so does Instagram. Google+ has a variant that uses + instead of @, and even the long-form article platform Medium, whose founder Ev Williams also co-founded Twitter, quickly joined the @mentions party.

The biggest communications problem on the internet

If you use Twitter, your friend Alice only uses Facebook, your friend Bob only uses his blog on WordPress, and your pal Chuck is over on Medium, it’s impossible for any one of you to @mention another. You’re all on different and competing platforms, none of which interoperate to send these mentions or notifications of them. The only way to communicate in this way is if you all join the same social media platforms, resulting in the average person being signed up to multiple services just to stay in touch with all their friends and acquaintances.

Given the issues of privacy and identity protection, different use cases, the burden of additional usernames and passwords, and the time involved, many people don’t want to do this. Possibly worst of all, your personal identity on the internet can end up fragmented like a Horcrux across multiple websites over which you have little, if any, control.

Imagine if AT&T customers could only speak to other AT&T customers and needed a separate phone, account, and phone number to speak to friends and family on Verizon. And still another to talk to friends on Sprint or T-Mobile. The massive benefit of the telephone system is that if you have a telephone and service (from any one of hundreds or even thousands of providers worldwide), you can potentially reach anyone else using the network. Surely, with a basic architecture based on simple standards, links, and interconnections, the same should apply to the internet?

The solution? Enter Webmentions!

As mentioned earlier, Webmentions allow notifications between web addresses. If both sites are set up to send and receive them, the system works like this:

  1. Alice has a website where she writes an article about her rocket engine hobby.
  2. Bob has his own website where he writes a reply to Alice’s article. Within his reply, Bob includes the permalink URL of Alice’s article.
  3. When Bob publishes his reply, his publishing software automatically notifies Alice’s server that her post has been linked to by the URL of Bob’s reply.
  4. Alice’s publishing software verifies that Bob’s post actually contains a link to her post and then (optionally) includes information about Bob’s post on her site; for example, displaying it as a comment.

A Webmention is simply an @mention that works from one website to another!

If she chooses, Alice can include the full text of Bob’s reply—along with his name, photo, and his article’s URL (presuming he’s made these available)—as a comment on her original post. Any new readers of Alice’s article can then see Bob’s reply underneath it. Each can carry on a full conversation from their own websites and in both cases display (if they wish) the full context and content.

Using Webmentions, both sides can carry on a conversation where each is able to own a copy of the content and provide richer context.

User behaviors with Webmentions are a little different than they are with @mentions on Twitter and the like in that they work between websites in addition to within a particular website. They enable authors (of both the original content and the responses) to own the content, allowing them to keep a record on the web page where it originated, whether that’s a website they own or the third-party platform from which they chose to send it.

Interaction examples with Webmention

Webmentions certainly aren’t limited to creating or displaying “traditional” comments or replies. With the use of simple semantic microformats classes and a variety of parsers written in numerous languages, one can explicitly post bookmarks, likes, favorites, RSVPs, check-ins, listens, follows, reads, reviews, issues, edits, and even purchases. The result? Richer connections and interactions with other content on the web and a genuine two-way conversation instead of a mass of unidirectional links. We’ll take a look at some examples, but you can find more on the IndieWeb wiki page for Webmention alongside some other useful resources.

Marginalia

With Webmention support, one could architect a site to allow inline marginalia and highlighting similar to Medium.com’s relatively well-known functionality. With the clever use of URL fragments, which are well supported in major browsers, there are already examples of people who use Webmentions to display word-, sentence-, or paragraph-level marginalia on their sites. After all, aren’t inline annotations just a more targeted version of comments?

An inline annotation on the post “Hey Ev, what about mentions?,” in which Medium began to roll out their @mention functionality. Reads

As another example, and something that could profoundly impact the online news business, I might post a link on my website indicating I’ve read a particular article on, say, The New York Times. My site sends a “read” Webmention to the article, where a facepile or counter showing the number of read Webmentions received could be implemented. Because of the simplified two-way link between the two web pages, there is now auditable proof of interaction with the content. This could similarly work with microinteractions such as likes, favorites, bookmarks, and reposts, resulting in a clearer representation of the particular types of interaction a piece of content has received. Compared to an array of nebulous social media mini-badges that provide only basic counters, this is a potentially more valuable indicator of a post’s popularity, reach, and ultimate impact.

Listens

Building on the idea of using reads, one could extend Webmentions to the podcasting or online music sectors. Many platforms are reasonably good at providing download numbers for podcasts, but it is far more difficult to track the number of actual listens. This can have a profound effect on the advertising market that supports many podcasts. People can post about what they’re actively listening to (either on their personal websites or via podcast apps that could report the percentage of the episode listened to) and send “listen” Webmentions to pages for podcasts or other audio content. These could then be aggregated for demographics on the back end or even shown on the particular episode’s page as social proof of the podcast’s popularity.

For additional fun, podcasters or musicians might use Webmentions in conjunction with media fragments and audio or video content to add timecode-specific, inline comments to audio/video players to create an open standards version of SoundCloud-like annotations and commenting.

SoundCloud allows users to insert inline comments that dovetail with specific portions of audio. Reviews

Websites selling products or services could also accept review-based Webmentions that include star-based ratings scales as well as written comments with photos, audio, or even video. Because Webmentions are a two-way protocol, the reverse link to the original provides an auditable path to the reviewer and the opportunity to assess how trustworthy their review may be. Of course, third-party trusted sites might also accept these reviews, so that the receiving sites can’t easily cherry-pick only positive reviews for display. And because the Webmention specification includes the functionality for editing or deletion, the original author has the option to update or remove their reviews at any time.

Getting started with Webmentions Extant platforms with support

While the specification has only recently become a broad recommendation for use on the internet, there are already an actively growing number of content management systems (CMSs) and platforms that support Webmentions, either natively or with plugins. The simplest option, requiring almost no work, is a relatively new and excellent social media service called Micro.blog, which handles Webmentions out of the box. CMSs like Known and Perch also have Webmention functionality built in. Download and set up the open source software and you’re ready to go.

If you’re working with WordPress, there’s a simple Webmention plugin that will allow you to begin using Webmentions—just download and activate it. (For additional functionality when displaying Webmentions, there’s also the recommended Semantic Linkbacks plugin.) Other CMSs like Drupal, ProcessWire, Elgg, Nucleus CMS, Craft, Django, and Kirby also have plugins that support the standard. A wide variety of static site generators, like Hugo and Jekyll, have solutions for Webmention technology as well. More are certainly coming.

If you can compose basic HTML on your website, Aaron Parecki has written an excellent primer on “Sending Your First Webmention from Scratch.”

A weak form of Webmention support can be bootstrapped for Tumblr, WordPress.com, Blogger, and Medium with help from the free Bridgy service, but the user interface and display would obviously be better if they were supported fully and natively.

As a last resort, if you’re using Tumblr, WordPress.com, Wix, Squarespace, Ghost, Joomla, Magento, or any of the other systems without Webmention, file tickets asking them to support the standard. It only takes a few days of work for a reasonably experienced developer to build support, and it substantially improves the value of the platform for its users. It also makes them first-class decentralized internet citizens.

Webmentions for developers

If you’re a developer or a company able to hire a developer, it is relatively straightforward to build Webmentions into your CMS or project, even potentially open-sourcing the solution as a plugin for others. For anyone familiar with the old specifications for pingback or trackback, you can think of Webmentions as a major iteration of those systems, but with easier implementation and testing, improved performance and display capabilities, and decreased spam vulnerabilities. Because the specification supports editing and deleting Webmentions, it provides individuals with more direct control of their data, which is important in light of new laws like GDPR.

In addition to reading the specification, as mentioned previously, there are multiple open source implementations already written in a variety of languages that you can use directly, or as examples. There are also a test suite and pre-built services like Webmention.io, Telegraph, mention-tech, and webmention.herokuapp.com that can be quickly leveraged.

Maybe your company allows employees to spend 20% of their time on non-specific projects, as Google does. If so, I’d encourage you to take the opportunity to fbuild Webmentions support for one or more platforms—let’s spread the love and democratize communication on the web as fast as we can!

And if you already have a major social platform but don’t want to completely open up to sending and receiving Webmentions, consider using Webmention functionality as a simple post API. I could easily see services like Twitter, Mastodon, or Google+ supporting the receiving of Webmentions, combined with a simple parsing mechanism to allow Webmention senders to publish syndicated content on their platform. There are already several services like IndieNews, with Hacker News-like functionality, that allow posting to them via Webmention.

If you have problems or questions, I’d recommend joining the IndieWeb chat room online via IRC, web interface, Slack, or Matrix to gain access to further hints, pointers, and resources for implementing a particular Webmention solution.

The expansion of Webmentions

The big question many will now have is Will the traditional social media walled gardens like Facebook, Twitter, Instagram, and the like support the Webmention specification?

At present, they don’t, and many may never do so. After all, locking you into their services is enabling them to leverage your content and your interactions to generate income. However, I suspect that if one of the major social platforms enabled sending/receiving Webmentions, it would dramatically disrupt the entire social space.

In the meantime, if your site already has Webmentions enabled, then congratulations on joining the next revolution in web communication! Just make sure you advertise the fact by using a button or badge. You can download a copy here.

Categories: Technology

Order Out of Chaos: Patterns of Organization for Writing on the Job

A list Apart development site - Thu, 07/05/2018 - 09:18

A few years ago, a former boss of mine emailed me out of the blue and asked for a resource that would help him and his colleagues organize information more effectively. Like a dutiful friend, I sent him links to a few articles and the names of some professional writing books. And I qualified my answer with that dreaded disclaimer: “Advice varies widely depending on the situation.” Implication: “You’ll just have to figure out what works best for you. So, good luck!”

In retrospect, I could have given him a better answer. Much like the gestalt principles of design that underpin so much of what designers do, there are foundational principles and patterns of organization that are relevant to any professional who must convey technical information in writing, and you can adapt these concepts to bring order out of chaos whether or not you’re a full-time writer.

.row{margin:0 132px 24px}.col ol,.col ul{margin-left:40px}.row:after{clear:left;content:"";display:block}.col{float:left;width:50%}.col ul{list-style-type:disc}.col ul li{margin-bottom:9px}@media only screen and (max-width:37.5em){.row{margin:0 0 24px}.col{float:none;width:100%}.col+.col{margin-top:24px}} Recognize the primary goals: comprehension and performance

Not long after I wrote my response, I revisited a book I’d read in college: Technical Editing, by Carolyn D. Rude. In my role as a technical writer, I reference the book every now and then for practical advice on revising software documentation. This time, as I reviewed the chapter on organization, I realized that Rude explained the high-level goals and principles better than any other author I’d read up to that point.

In short, she says that whether you are outlining a procedure, describing a product, or announcing a cool new feature, a huge amount of writing in the workplace is aimed at comprehension (here’s what X is and why you should care) and performance (here’s how to do X). She then suggests that editors choose from two broad kinds of order to support these goals: content-based order and task-based order. The first refers to structures that guide readers from major sections to more detailed sections to facilitate top-down learning; the second refers to structures of actions that readers need to carry out. Content-based orders typically start with nouns, whereas task-based orders typically begin with verbs.

Content-Based Order Example

Product Overview

  • Introduction
  • Features
    • Feature 1
    • Feature 2
    • Feature n
  • Contact
  • Support

Task-Based Order Example

User Guide (WordPress)

  • Update your title and tagline
  • Pick a theme you love
  • Add a header or background
  • Add a site icon
  • Add a widget

Of course, not all writing situations fall neatly into these buckets. If you were to visit Atlassian’s online help content, you would see a hybrid of content-based topics at the first level and task-based topics within them. The point is that as you begin to think about your organization, you should ask yourself:

  • Which of the major goals of organization (comprehension or performance) am I trying to achieve?
  • And which broad kind of order will help me best achieve those goals?

This is still pretty abstract, so let’s consider the other principles from Carolyn Rude, but with a focus on how a writer rather than an editor should approach the task of organization.1

Steal like an organizer: follow pre-established document structures

In his book Steal Like an Artist, Austin Kleon argues that smart artists don’t actually create anything new but rather collect inspiring ideas from specific role models, and produce work that is profoundly shaped by them.

“If we’re free from the burden of trying to be completely original,” he writes, “we can stop trying to make something out of nothing, and we can embrace influence instead of running away from it.”

The same principle applies to the art of organization. To “steal like an organizer” means to look at what other people have written and to identify and follow pre-established structures that may apply to your situation. Doing so not only saves time and effort but also forces you to remember that your audience may already expect a particular pattern—and experience cognitive dissonance if they don’t get it.

You are probably familiar with more pre-established structures than you think. News reports follow the inverted pyramid. Research reports often adhere to some form of the IMRAD structure (Introduction, Methodology, Results, and Discussion). Instruction manuals typically have an introductory section followed by tasks grouped according to the typical sequence a user would need to follow. Even troubleshooting articles tend to have a standard structure of Problem, Cause, and Solution.

All this may sound like common sense, and yet many writers entirely skip this process of adapting pre-made structures. I can understand the impulse. When you face a blank screen, it feels simpler to capture the raw notes and organize it all later. That approach can certainly help you get into the flow, but it may also result in an ad hoc structure that fails to serve readers who are less familiar with your material.

Instead, when you begin the writing process, start by researching available templates or pre-made structures that could support your situation. Standard word processors and content management systems already contain some good templates, and it’s easy to search for others online. Your fellow writers and designers are also good resources. If you’re contributing to a series of documents at your organization, you should get familiar with the structure of that series and learn how to work within it. Or you can do some benchmarking and steal some ideas from how other companies structure similar content.

My team once had to do our own stealing for a major project that affected about half our company. We needed to come up with a repeatable structure for standard operating procedures (SOPs) that any employee could use to document a set of tasks. Knowing SOPs to be a well-established genre, we found several recommended structures online and in books, and came up with a list of common elements. We then decided which ones to steal and arranged them into a sequence that best suited our audience. We made out like bandits.

Structural SOP Elements We Found Our Assessment Overview Steal Roles Involved Steal Dependencies Steal Estimated Level of Effort Nah, too hard to calculate and maintain. Process Diagram Meh, kind of redundant, not to mention a lot of work. No thanks. Tasks Steal Task n Steal Task n Introduction Steal Task n Responsibility Steal Task n Steps Steal See Also Steal

But what if there is no pre-established pattern? Or what if a pattern exists, but it’s either too simple or too complex for what you’re trying to accomplish? Or what if it’s not as user-friendly as you would like?

There may indeed be cases where you need to develop a mostly customized structure, which can be daunting. But fear not! That’s where the other principles of organization come in.

Anticipate your readers’ questions (and maybe even talk to them)

Recently I had an extremely frustrating user experience. While consulting some documentation to learn about a new process, I encountered a series of web pages that gave no introduction and dove straight into undefined jargon and acronyms that I had never heard of. When I visited related pages to get more context, I found the same problem. There was no background information for a newbie like me. The writers failed in this case to anticipate my questions and instead assumed a great deal of prior knowledge.

Don’t make this mistake when you design your structure. Like a journalist, you need to answer the who, what, where, when, how, and why of your content, and then incorporate the answers in your structure. Anticipate common questions, such as “What is this? Where do I start? What must I know? What must I do?” This sort of critical reflection is all the more important when organizing web content, because users will almost certainly enter and exit your pages in nonlinear, unpredictable ways.

If possible, you should also meet with your readers, and gather information about what would best serve them. One simple technique you could try is to create a knowledge map, an annotated matrix of sorts that my team once built after asking various teams about their information priorities. On the left axis, we listed categories of information that we thought each team needed. Along the top axis, we listed a column for each team. We then gave team representatives a chance to rank each category and add custom categories we hadn’t included. (You can learn more about the process we followed in this video presentation.)

A knowledge map my team created after asking other teams which categories of information were most important to them.

The weakness of this approach is that it doesn’t reveal information that your audience doesn’t know how to articulate. To fill in this gap, I recommend running a few informal usability tests. But if you don’t have the time for that, building a knowledge map is better than not meeting with your readers at all, because it will help you discover structural ideas you hadn’t considered. Our knowledge map revealed multiple categories that were required across almost all teams—which, in turn, suggested a particular hierarchy and sequence to weave into our design.

Go from general to specific, familiar to new

People tend to learn and digest information best by going from general to specific, and familiar to new. By remembering this principle, which is articulated in the schema theory of learning, you can better conceptualize the structure you’re building. What are the foundational concepts of your content? They should appear in your introductory sections. What are the umbrella categories under which more detailed categories fall? The answer should determine which headings belong at the top and subordinate levels of your hierarchy. What you want to avoid is presenting new ideas that don’t flow logically from the foundational concepts and expectations that your readers bring to the table.

Consider the wikiHow article “How to Create a Dungeons and Dragons Character.” It begins by defining what Dungeons and Dragons is and explaining why you need to create a character before you can start playing the game.

Writers at wikiHow help readers learn by starting with general concepts before moving on to specifics.

The next section, “Part 1: Establishing the Basics,” guides the reader into subsequent foundational steps, such as deciding which version of the game to follow and printing out a character sheet. Later sections (“Selecting a gender and race,” “Choosing a class,” and “Calculating ability scores”) expand on these concepts to introduce more specific, unfamiliar ideas in an incremental fashion, leading readers up a gentle ramp into new territory.

Use conventional patterns to match structure to meaning

Within the general-to-specific/familiar-to-new framework, you can apply additional patterns of organization that virtually all humans understand. Whereas the pre-established document structures above are usually constructed for particular use cases or genres, other conventional patterns match more general mental models (or “schemas,” as the schema theory so elegantly puts it) that we use to make sense of the world. These patterns include chronological, spatial, comparison-contrast, cause-effect, and order of importance.

Chronological

The chronological pattern reveals time or sequence. It’s appropriate for things like instructions, process flows, progress reports, and checklists. In the case of instructions, the order of tasks on a page often implies (or explicitly states) the “proper” or most common sequence for a user to follow. The wikiHow article above, for example, offers a recommended sequence of tasks for beginner players. In the case of progress reports, the sections may be ordered according to the periods of time in which work was done, as in this sample outline from the book Reporting Technical Information, by Kenneth W. Houp et al.:

Beginning

  • Introduction
  • Summary of work completed

Middle

  • Work completed
    • Period 1 (beginning and end dates)
      • Description
      • Cost
    • Period 2 (beginning and end dates)

      • Description
      • Cost
  • Work remaining

    • Period 3 (or remaining periods)
      • Description of work to be done
      • Expected cost

End

  • Evaluation of work in this period
  • Conclusions and recommendations

The principles of organization listed in this article are in fact another example of the chronological pattern. As Carolyn Rude points out in her book, the principles are arranged as a sort of methodology to follow. Try starting at the top of the list and work your way down. You may find it to be a useful way to produce order out of the chaos before you.

Spatial

The spatial pattern refers to top-to-bottom, left-to-right structures of organization. This is a good pattern if you need to describe the components of an interface or a physical object.

Take a look at the neighbor comparison graph below, which is derived from a sample energy efficiency solution offered by Oracle Utilities. Customers who see this graph would most likely view it from top to bottom and left to right.

A neighbor comparison graph that shows a customer how they compare with their neighbors in terms of energy efficiency.

A detailed description of this feature would then describe each component in that same order. Here’s a sample outline:

  • Feature name
    • Title
    • Bar chart
      • Efficient neighbors
      • You
      • Average neighbors
    • Date range
    • Performance insight

      • Great
      • Good
      • Using more than average
    • Energy use insight
    • Comparison details (“You’re compared with 10 homes within 6 miles …”)
Comparison-contrast

The comparison-contrast pattern helps users weigh options. It’s useful when reporting the pros and cons of different decisions or comparing the attributes of two or more products or features. You see it often when you shop online and need to compare features and prices. It’s also a common pattern for feasibility studies or investigations that list options along with upsides and downsides.

Cause-effect

The cause-effect pattern shows relationships between actions and reactions. Writers often use it for things like troubleshooting articles, medical diagnoses, retrospectives, and root cause analyses. You can move from effect to cause, or cause to effect, but you should stick to one direction and use it consistently. For example, the cold and flu pages at Drugs.com follow a standard cause-effect pattern that incorporates logical follow-up sections such as “Prevention” and “Treatment”:

  • What Is It? (This section defines the illness and describes possible “causes.”)
  • Symptoms (This section goes into the “effects” of the illness.)
  • Diagnosis
  • Expected Duration
  • Prevention
  • Treatment
  • When to Call a Professional
  • Prognosis

For another example, see the “Use parallel structure for parallel sections” section below, which shows what a software troubleshooting article might look like.

Order of importance

The order of importance pattern organizes sections and subsections of content according to priority or significance. It is common in announcements, marketing brochures, release notes, advice articles, and FAQs.

The order of importance pattern is perhaps the trickiest one to get right. As Carolyn Rude says, it’s not always clear what the most important information is. What should come in the beginning, middle, and end? Who decides? The answers will vary according to the author, audience, and purpose.

When writing release notes, for example, my team often debates which software update should come first, because we know that the decision will underscore the significance of that update relative to the others. FAQs by definition are focused on which questions are most common and thus most important, but the exact order will depend on what you perceive as being the most frequent or the most important for readers to know. (If you are considering writing FAQs, I recommend this great advice from technical writer Lisa Wright.)

Other common patterns

Alphabetical order is a common pattern that Rude doesn’t mention in detail but that you may find helpful for your situation. To use this pattern, you would simply list sections or headings based on the first letter of the first word of the heading. For example, alphabetical order is used frequently to list API methods in API documentation sites such as those for Flickr, Twitter, and Java. It is also common in glossaries, indexes, and encyclopedic reference materials where each entry is more or less given equal footing. The downside of this pattern is that the most important information for your audience may not appear in a prominent, findable location. Still, it is useful if you have a large and diverse set of content that defies simple hierarchies and is referenced in a non-linear, piecemeal fashion.

Group related material

Take a look at the lists below. Which do you find easier to scan and digest?

  1. Settle on a version of D&D.
  2. Print a character sheet, if desired.
  3. Select a gender and race.
  4. Choose a class.
  5. Name your character.
  6. Identify the main attributes of your character.
  7. Roll for ability scores.
  8. Assign the six recorded numbers to the six main attributes.
  9. Use the “Point Buy” system, alternatively.
  10. Generate random ability scores online.
  11. Record the modifier for each ability.
  12. Select skills for your character.
  13. List your character’s feats.
  14. Roll for your starting gold.
  15. Equip your character with items.
  16. Fill in armor class and combat bonuses.
  17. Paint a picture of your character.
  18. Determine the alignment of your character.
  19. Play your character in a campaign.

Part 1: Establishing the Basics

  1. Settle on a version of D&D.
  2. Print a character sheet, if desired.
  3. Select a gender and race.
  4. Choose a class.
  5. Name your character.

Part 2: Calculating Ability Scores

  1. Identify the main attributes of your character.
  2. Roll for ability scores.
  3. Assign the six recorded numbers to the six main attributes.
  4. Use the “Point Buy” system, alternatively.
  5. Generate random ability scores online.
  6. Record the modifier for each ability.

Part 3: Equipping Skills, Feats, Weapons, and Armor

  1. Select skills for your character.
  2. List your character’s feats.
  3. Roll for your starting gold.
  4. Equip your character with items.
  5. Fill in armor class and combat bonuses.

Part 4: Finishing Your Character

  1. Paint a picture of your character.
  2. Determine the alignment of your character.
  3. Play your character in a campaign.

(Source: wikiHow: How to Create a Dungeons and Dragons Character.)

If you chose the second list, that is probably because the writers relied on a widely used organizational technique: grouping.

Grouping is the process of identifying meaningful categories of information and putting information within those categories to aid reader comprehension. Grouping is especially helpful when you have a long, seemingly random list of information that could benefit from an extra layer of logical order. An added benefit of grouping is that it may reveal where you have gaps in your content or where you have mingled types of content that don’t really belong together.

To group information effectively, first analyze your content and identify the discrete chunks of information you need to convey. Then tease out which chunks fall within similar conceptual buckets, and determine what intuitive headings or labels you can assign to those buckets. Writers do this when creating major and minor sections within a book or printed document. For online content, grouping is typically done at the level of articles or topics within a web-based system, such as a wiki or knowledge base. The Gmail Help Center, for example, groups topics within categories like “Popular articles,” “Read & organize emails,” and “Send emails.”

It’s possible to go overboard here. Too many headings in a short document or too many topics in a small help system can add unnecessary complexity. I once faced the latter scenario when I reviewed a help system written by one of my colleagues. At least five of the topics were so short that it made more sense to merge them together on a single page rather than forcing the end user to click through to separate pages. I’ve also encountered plenty of documents that contain major section headings with only one or two sentences under them. Sometimes this is fine; you may need to keep those sections for the sake of consistency. But it’s worth assessing whether such sections can simply be merged together (or conversely, whether they should be expanded to include more details).

Because of scenarios like these, Carolyn Rude recommends keeping the number of groupings to around seven, give or take a few—though, as always, striking the right balance ultimately depends on your audience and purpose, as well as the amount of information you have to manage.

Use parallel structure for parallel sections

One of the reasons Julius Caesar’s phrase “I came, I saw, I conquered” still sticks in our memory after thousands of years is the simple fact of parallelism. Each part of the saying follows a distinct, repetitive grammatical form that is easy to recall.

Parallelism works in a similar manner with organization. By using a consistent and repetitive structure across types of information that fit in the same category, you make it easier for your readers to navigate and digest your content.

Imagine you’re writing a troubleshooting guide in which all the topics follow the same basic breakdown: Problem Title, Problem, Cause, Solution, and See Also. In this case, you should make sure that each topic includes those same headings, in the exact same hierarchy and sequence, and using the exact same style and formatting. This kind of parallelism delivers a symmetry that reduces the reader’s cognitive load and clarifies the relationships of each part of your content. Deviations from the pattern not only cause confusion but can undermine the credibility of the content.

Do This

ABC Troubleshooting Guide

  • Introduction
  • Problem 1 Title
    • Problem
    • Cause
    • Solution
    • See Also
  • Problem 2 Title

    • Problem
    • Cause
    • Solution
    • See Also
  • Problem 3 Title

    • ...
  • Don’t Do This

    ABC Troubleshooting Guide

    • Introduction
    • Problem 1 Title
      • Problem
      • Root causes
      • How to Fix it
      • Advanced Tips and tricks
      • Related
    • Problem 2 title

      • Issue
      • Steps to Fix
      • Why did this happen, and how can I avoid it next time?
      • See also
    • Problem 3 title

      • ...

    This last principle is probably the easiest to grasp but may be the most difficult to enforce, especially if you are managing contributions from multiple authors. Templates and style guides are useful here because they invite authors to provide standard inputs, but you will still need to watch the content like a hawk to squash the inconsistencies that inevitably emerge.

    Conclusion

    In one sense, my response to my former boss was accurate. Given the endless variety of writing situations, there is no such thing as a single organization solution. But saying that “advice varies widely depending on the situation” doesn’t tell the whole story. There are flexible patterns and principles that can guide you in finding, customizing, and creating structures for your goals.

    The key thing to remember is that structure affects meaning. The sequence of information, the categories you use, the emphasis you imply through your hierarchy—all of these decisions impact how well your audience understands what you write. Your ideal structure should therefore reinforce what you mean to say.

    Footnotes
    • 1. The principles in this article are based on the same ones that Carolyn Rude outlines in chapter 17, pp. 289–296, of the third edition of her book. I highly recommend it for anyone who’s interested in gaining an in-depth understanding of editing. The book is now in its fifth edition and includes an additional author, Angela Eaton. See Technical Editing (Fifth Edition) for details. The examples and illustrations used in this article are derived from a variety of other sources, including my own work.
Categories: Technology

Building a SAN-less private cloud with IBM PowerVM and IBM PowerVC

IBM Redbooks Site - Fri, 06/29/2018 - 09:30
Draft Redpaper, last updated: Fri, 29 Jun 2018

This IBM® Redpaper™ publication describes a software-defined infrastructure (SDI) Solution with PowerVC.

Categories: Technology

Db2 Utilities in Practice

IBM Redbooks Site - Fri, 06/29/2018 - 09:30
Redpaper, published: Fri, 29 Jun 2018

As IBM® continues to enhance the functionality, performance, and availability of IBM Db2®, the utilities have made significant strides towards self-management.

Categories: Technology

Your Emails (and Recipients) Deserve Better Context

A list Apart development site - Thu, 06/28/2018 - 09:05

Email communication is an integral part of the user experience for nearly every web application that requires a login. It’s also one of the first interactions the user has after signing up. Yet too often both the content and context of these emails is treated as an afterthought (at best), with the critical parts that users see first—sender name and email, subject, and preheader—largely overlooked. Your users, and the great application you’ve just launched, deserve better.

A focus on recipient experience

Designing and implementing a great email recipient experience is difficult. And by the time it comes to the all-important context elements (name, subject, and so on), it’s commonly left up to the developer to simply fill something in and move on. That’s a shame, because these elements play an outsized role in the email experience, being not only the first elements seen but also the bits recipients use to identify emails when searching through their archives. Given the frequency with which they touch users, it really is time we started spending a little more effort to fine-tune them.

The great news is that despite the constraints imposed on these elements, they’re relatively easy to improve, and they can have a huge impact on engagement, open rates, and recipient satisfaction. When they all work together, sender name and email, subject, and preheader provide a better experience for your recipients.

So whether you’re a developer stuck fixing such oversights and winging it, or on the design or marketing team responsible for making the decisions, use the following guide to improve your recipient’s experience. And, if possible, bring it up with your whole team so it’s always a specific requirement in the future.

Details that matter

As they say, the devil is in the details, and these details matter. Let’s start with a quick example that highlights a few common mistakes.

In the image below, the sender is unnecessarily repeated within the subject, wasting key initial subject characters, while the subjects themselves are all exactly the same. This makes it difficult to tell one email from the next, and the preview content doesn’t help much either since the only unique information it provides is the date (which is redundant alongside the email’s time stamp). The subject copy could be more concise as well—“Payment Successfully Processed” is helpful, but it’s a bit verbose.

Avoid redundancy and make your sender name, subject, and preheaders work together. Periscope repeats the sender name, and doesn’t provide unique or relevant information in the subject or preheader.

Outside of the sender and the dates on the emails, there’s not much useful information until you open the email itself. Fortunately, none of these things are particularly difficult to fix. Weather Underground provides a great example of carefully crafted emails. The subject conveys the most useful information without even requiring the recipient to open the email. In addition, their strategic use of emojis helps complement that information with a very rich, yet judicious, use of subject-line space.

Weather Underground does a great job with the sender and even front-loads the subject with the most valuable bit of information. The date is included, but it’s at the end of the subject.

Weather Underground also makes use of Gmail Inbox Actions to provide a direct link to the key information online without needing a recipient to open the email to follow a link. Gmail Inbox Actions require some extra work to set up and only work in Gmail, but they can be great if you’re sending high volumes of email.

Both scenarios involve recurring emails with similar content from one to the next, but the difference is stark. With just a little effort and fine-tuning, the resulting emails are much more useful to the recipients. Let’s explore how this is done.

Emphasizing unique content for recurring emails

With the earlier examples, both organizations are sending recurring emails, but by focusing on unique subject lines, Weather Underground’s emails are much more helpful. Recurring emails like invoices may not contain the most glamorous content, but you still have an opportunity to make each one unique and informative.

Instead of a generic “You have a new invoice” notification, you can surface important or unique information like the invoice total, the most expensive products or services, or the due date.

By surfacing the most important or unique information from the content of the email, there’s additional context to help the recipient know whether they need to act or not. It also makes it easier to find a specific invoice when searching through emails in the future.

Clarifying the sender

Who (or what) is sending this email? Is it a person? Is it automated? Do I want to hear from them? Do I trust them? Is this spam? These questions and more automatically run through our heads whenever we see an email, and the sender information provides the first clue when we start processing our inbox. Just as for caller ID on incoming phone calls, recognition and trust both play a role. As Joanna Wiebe said in an interview with Litmus, “If the from name doesn’t sound like it’s from someone you want to hear from, it doesn’t matter what the subject line is.” This can be even more critical on mobile devices where the sender name is the most prominent element.

The first and most important step is to explicitly specify a name. You don’t want the recipient’s email client choosing what to display based on the email address alone. For instance, if you send emails from “alerts@example.com” (with no name specified), some clients will display “alerts” as the name, and others will display “alerts@example.com.” With the latter, it just feels rough around the edges. In either case, the experience is less than ideal for the sender.

Without a name specified, email clients may use the username portion of an email address or truncate longer email addresses, making the name portion incomplete or less helpful to recipients.

The technical implementation may vary depending on your stack, but at the simplest level, correct implementation is all in the string formatting. Let’s look at “Jane Doe <email@example.com>” as an example. “Jane Doe” is the name, and the email is included after the name and surrounded by angle brackets. It’s a small technical detail, but it makes a world of difference to recipients.

But what name should we show? This depends on the type of email, so you’ll want to consider the sender for each email independently. For example, with a receipt or invoice you may want to use “Acme Billing.” But with a comment notification, it may be more informative for recipients if you use the commenter’s name, such as “Jane Doe via AcmeApp.” Depending on the context, you could use “with” or “from” as well, but those have an extra character, so I’ve found “via” to be the shortest and most semantically accurate option.

Similarly, if your business entity or organization name is different from your product name, you should use the name that will be most familiar to your recipients.

Recipients aren’t always familiar with the names of corporate holding companies, so make sure to use the company or product name that will be most familiar to the recipient. In the above cases, while “Jane Doe” may have made the comment, the email isn’t directly from her, so it’s best to add something lik “via Acme Todos” to make it clear that it was sent on Jane’s behalf. In the case of “Support,” content doesn’t clarify which product it refers to. Since users could have a variety of emails from “Support” for different products, it fails to provide important context. Avoiding contact confusion

In the case where you use someone’s name—like with the “Jane Doe via AcmeApp” example above—it’s important to add a reference to the app name. Since the email isn’t actually from Jane, it’s inaccurate to represent that it’s from Jane Doe directly. This can be confusing for users, but it can also create problems with address books. If you use just “Jane Doe,” your sending email address can be accidentally added to the recipient’s address book in association with Jane’s entry. Then, when they go to email Jane later, they may unwittingly send an email to “notifications@acme.com” instead of Jane. That could lead to some painful missed emails and miscommunication. The other reason is that it’s simply helpful for the recipient to know the source of the email. It’s not just from Jane, it’s from Jane via your application.

You’ll also want to put yourself in your recipient’s shoes and carefully consider whether a name is recognizable to your recipient. For example, if your corporate entity name and product name aren’t the same, recipients will be much less likely to recognize the sender if you use the name of your corporate entity. So make sure to use the product name that will be most familiar to the recipient. Similarly, you’ll want to avoid using generic names that could be from any company. For example, use “Acme Billing” instead of just “Billing,” so the recipient can quickly and easily identify your product.

Finally, while names are great, the underlying sending address can be just as important. In many ways, it’s the best attribute for recipients to use when filtering and organizing their inbox, and using unique email addresses or aliases for different categories of emails makes this much easier. There’s a fine line, but the simplest way to do this is to group emails into three categories: billing, support, and activity/actions. You may be able to use more, like notifications, alerts, or legal, but remember that the more you create, the more you’ll have to keep track of.

Also, keep the use of subdomains to a minimum. By consistently only sending transactional email like password resets, receipts, order updates, and other similar emails from your primary domain, users learn to view any emails from other domains as suspicious. It may seem like a minor detail, but these bits of information add up to create important signals for recipients. It is worth noting, however, that you should use a different address, and ideally a separate subdomain, for your bulk marketing emails. This helps Gmail and other inbox providers understand the type of email coming from each source, which in turn helps ensure the domain reputation for your bulk marketing emails—which is traditionally lower—doesn’t affect delivery of your more critical transactional email.

Subject line utility

Now that recipients have clearly identifiable and recognizable sender information, it’s time to think about the subjects of your emails. Since we’ve focused on transactional emails in the examples used so far, we’ll similarly focus on the utility of your subject line content rather than the copywriting. You can always use copywriting to improve the subject, but with transactional emails, utility comes first.

The team at MailChimp has studied data about subject lines extensively, and there are a few key things to know about subjects. First, the presence of even a single word can have a meaningful impact on open rates. A 2015 report by Adestra had similar findings. Words and phrases like “thank you,” “monthly,” and “thanks” see higher engagement than words like “subscription,” “industry,” and “report,” though different words will have different impacts depending on your industry, so you’ll still need to test and monitor the results. Personalization can also have an impact, but remember, personalization isn’t just about using a person’s name. It can be information like location, previous purchases, or other personal data. Just remember that it’s important to be tasteful, judicious, and relevant.

The next major point from MailChimp is that subject line length doesn’t matter. Or, rather, it doesn’t matter directly. After studying 6 billion emails, they found “little or no correlation between performance and subject length.” That said, when line length is considered as one aspect of your overall subject content, it can be used to help an email stand out. Clarity and utility are more important than brevity, but when used as a component to support clarity and utility, brevity can help.

One final point from the Adestra report is that open rates aren’t everything. Regardless of whether someone opens an email, the words and content of your subject line leaves an impression. So even if a certain change doesn’t affect your open rates, it can still have a far-reaching impact.

Clearing out redundancy

The most common mistake with subjects is including redundant information. If you’ve carefully chosen the sender name and email address, there’s no need to repeat the sender name in the subject, and the characters could be better applied to telling the recipient additional useful information. Dates are a bit of a gray area, but in many cases, the email’s time stamp can suffice for handling any time-based information. On the other hand, when the key dates don’t correlate to when the email was sent, it can be helpful to include the relevant date information in the subject.

With these examples, after the sender, there’s no new or useful information displayed, and some form of the company name is repeated several times. Even the preheader is neglected leaving the email client to use alternate text from the logo.

With the subject of your application emails, you’ll also want to front-load the most important content to prevent it from being cut off. For instance, instead of “Your Invoice for May 2018,” you could rewrite that as “May 2018 Invoice.” Since your sender is likely “Acme Billing,” the recipient already knows it’s about billing, so the month and year is the most important part of the subject. However, “May 2018 Invoice” is a bit terse, so you may want to add something at the end to make it more friendly.

Next, in situations where time stamps are relevant, avoid relying on relative dates or times. Phrases like “yesterday,” “last week,” or “two hours ago” don’t age well with email since you never know when someone will receive or read it. Similarly, when someone goes to search their email archives, relative dates aren’t helpful. If you must use relative dates, look for opportunities to add explicit dates or time stamps to add clarity.

With regularly occurring emails like reports or invoices, strive to give each message a unique subject. If every report has the subject “Your Monthly Status Report,” they can run together in a list of emails that all have the same subject. It can also make them more difficult to search later on. The same goes for invoices and receipts. Yes, invoice numbers and order numbers are technically unique, but they aren’t particularly helpful. Make sure to include useful content to help identify each email individually. Whether that’s the date, total value, listing the most expensive items, or all three, it’s easier on recipients when they can identify the contents of an email without having to open it. While open rates are central to measuring marketing emails, transactional emails are all about usefulness. So open rates aren’t as purely correlated with successful transactional emails.

There’s a case to be made that in some contexts a great transactional email doesn’t need to be opened at all for it to be useful. The earlier Weather Underground example does an excellent job communicating the key information without requiring recipients to open it. And while the subject is the best place for key content, some useful content can also be displayed using a preheader.

Making the most of preheaders

If you’re not familiar with the preheader, you can think of it as a convenient name for the content at the beginning of an email. Campaign Monitor has a great write-up with in-depth advice on making the most of your preheaders. It’s simply a way of acknowledging and explicitly suggesting the text that email clients should show in the preview pane for an email. While there’s no formal specification for preheaders, and different email clients will handle them differently, they’re still widely displayed.

Most importantly, well-written and useful preheaders of 40–50 characters have been shown to increase overall engagement, particularly if delivering a concise call to action. A study by Yes Lifecycle Marketing (signing up required) points out that preheader content is important, especially on mobile devices where subjects are truncated and it can act as a sort of extended subject.

If the leading content in your email is a logo or other image, email clients will often use the alternate text for the image as the preview text. Since “Acme Logo” isn’t very helpful, it’s best to include a short summary of text at the beginning of your email. Sometimes this short summary text can interfere with the design of your email, so it’s not uncommon for the design to accommodate some visually muted—but still readable—text at the beginning. Or, as long as you’re judicious, in most cases you can safely hide preheader text entirely by using the display: none CSS declaration. Abusing this could get you caught in spam filters, but for the most part, inbox providers seem to focus on the content that is hidden rather than the fact that it’s hidden.

If you’re not explicitly specifying your preheader text, there’s a good chance email clients will use content that at best is less than useful and at worst makes a bad impression.

If your email can be designed and written such that the first content encountered is the useful content for previews, then you’re all set. In the case of receipts, invoices, or activity summaries, that’s not always easy. In those cases, a short text-based summary of the content makes a good preheader.

Context element interplay

The rules outlined above are great guidelines, but remember that rules are there to be broken (well, sometimes …). As long as you understand the big picture, sender, subject, and preheader can still work together effectively even if some of those rules are bent. A bit. For example, if you ensure that you have relevant and unique content in your preheader for the preview, you may be able to get away with using the same subject for each recurring email. Alternatively, there may be cases where you need to repeat the sender name in the subject.

The key is that when you’re crafting these elements, make sure you’re looking at how they work together. Sometimes a subject can be shortened by moving some content into the preheader. Alternatively, you may be able to use a more specific sender to reduce the need for a word or two in the subject. The application of these guidelines isn’t black and white. Simply being aware of the recipient’s experience is the most important factor when crafting the elements they’ll see in preview panes.

Finally, a word on monitoring and testing

Simple changes to the sender, subject, and preheader can significantly impact open rates and recipient experience. One critical thing to remember, however, is that while some of these improvements are guaranteed winners, monitoring and testing things like open rates and click rates is critical to validate any changes made. And since these elements can either play against each other or work together, it’s best to test combinations and view all three elements holistically.

The value of getting this right really is in the details, and despite their tendency to be overlooked, taking the time to craft helpful and useful sender names and addresses, subject lines, and preheaders can drastically improve the experience for your email recipients. It’s a small investment that’s definitely worth your time.

Categories: Technology

Hortonworks Data Platform with IBM Spectrum Scale: Reference Guide for Building an Integrated Solution

IBM Redbooks Site - Tue, 06/26/2018 - 09:30
Redpaper, published: Tue, 26 Jun 2018

This IBM® Redpaper™ publication provides guidance on building an enterprise-grade data lake by using IBM Spectrum™ Scale and Hortonworks Data Platform for performing in-place Hadoop or Spark-based analytics.

Categories: Technology

Getting Started with IBM zHyperLink for z/OS

IBM Redbooks Site - Fri, 06/22/2018 - 09:30
Redpaper, published: Fri, 22 Jun 2018

With the pressures to drive transaction processing 24/7 because of online banking and other business demands, IBM® zHyperLink on the IBM DS8880 is making it easy to accelerate transaction processing for the mainframe.

Categories: Technology

Pages

Subscribe to www.hdgonline.net aggregator - Technology