TWW full feed

MadCap Flare 2018 Feature Highlight: A Look Into the Find and Replace Enhancements

Thu, 07 Jun 2018 15:30:48 +0000

Our recent webinar on “See What’s New in MadCap Flare 2018” covered the new features available with the new release, such as the lightweight editor, Elasticsearch, and more. In addition to these major new features, a number of smaller (but …

The post MadCap Flare 2018 Feature Highlight: A Look Into the Find and Replace Enhancements appeared first on MadBlog: The Official Technical Communications Blog for MadCap Software.

XML Documentation for Adobe Experience Manager 3.0 launched

Thu, 07 Jun 2018 14:05:54 +0000

We just released version 3.0 of XML Documentation for Adobe Experience Manager, Adobe’s enterprise-class DITA CCMS. See what’s new in this blog post by Product Manager Juhee Garg …

Orchestrating Experiences

Thu, 07 Jun 2018 13:04:00 +0000

A note from the editors: It’s our pleasure to share this excerpt from Chapter 2 (“Pinning Down Touchpoints”) of Orchestrating Experiences: Collaborative Design for Complexity by Chris Risdon and Patrick Quattlebaum, available now from Rosenfeld Media.

If you embrace the recommended collaborative approaches in your sense-making activities, you and your colleagues should build good momentum toward creating better and valuable end-to-end experiences. In fact, the urge to jump into solution mode will be tempting. Take a deep breath: you have a little more work to do. To ensure that your new insights translate into the right actions, you must collectively define what is good and hold one another accountable for aligning with it.

Good, in this context, means the ideas and solutions that you commit to reflect your customers’ needs and context while achieving organizational objectives. It also means that each touchpoint harmonizes with others as part of an orchestrated system. Defining good, in this way, provides common constraints to reduce arbitrary decisions and nudge everyone in the same direction.

How do you align an organization to work collectively toward the same good? Start with some common guidelines called experience principles.

A Common DNA

Experience principles are a set of guidelines that an organization commits to and follows from strategy through delivery to produce mutually beneficial and differentiated customer experiences. Experience principles represent the alignment of brand aspirations and customer needs, and they are derived from understanding your customers. In action, they help teams own their part (e.g., a product, touchpoint, or channel) while supporting consistency and continuity in the end-to-end experience. Figure 6.1 presents an example of a set of experience principles.

Figure 6.1: Example set of experience principles. Courtesy of Adaptive Path

Experience principles are not detailed standards that everyone must obey to the letter. Standards tend to produce a rigid system, which curbs innovation and creativity. In contrast, experience principles inform the many decisions required to define what experiences your product or service should create and how to design for individual, yet connected, moments. They communicate in a few memorable phrases the organizational wisdom for how to meet customers’ needs consistently and effectively. For example, look at the following:

Paint me a picture.
Have my back.
Set my expectations.
Be one step ahead of me.
Respect my time.

Experience Principles vs Design Principles
Orchestrating experiences is a team sport. Many roles contribute to defining, designing, and delivering products and services that result in customer experiences. For this reason, the label experience—rather than design—reflects the value of principles better that inform and guide the organization. Experience principles are outcome oriented; design principles are process oriented. Everyone should follow and buy into them, not just designers.

Patrick Quattlebaum

Experience principles are grounded in customer needs, and they keep collaborators focused on the why, what, and how of engaging people through products and services. They keep critical insights and intentions top of mind, such as the following:

Mental Models: How part of an experience can help people have a better understanding, or how it should conform to their mental model.
Emotions: How part of an experience should support the customer emotionally, or directly address their motivations.
Behaviors: How part of an experience should enable someone to do something they set out to do better.
Target: The characteristics to which an experience should adhere.
Impact: The outcomes and qualities an experience should engender in the user or customer.

Focusing on Needs to Differentiate
Many universal or heuristic principles exist to guide design work. There are visual design principles, interaction design principles, user experience principles, and any number of domain principles that can help define the best practices you apply in your design process. These are lessons learned over time that have a broader application and can be relied on consistently to inform your work across even disparate projects.

It’s important to reinforce that experience principles specific to your customers’ needs provide contextual guidelines for strategy and design decisions. They help everyone focus on what’s appropriate to specific customers with a unique set of needs, and your product or service can differentiate itself by staying true to these principles. Experience principles shouldn’t compete with best practices or universal principles, but they should be honored as critical inputs for ensuring that your organization’s specific value propositions are met.

Chris Risdon

Playing Together

Earlier, we compared channels and touchpoints to instruments and notes played by an orchestra, but in the case of experience principles, it’s more like jazz. While each member of a jazz ensemble is given plenty of room to improvise, all players understand the common context in which they are performing and carefully listen and respond to one another (see Figure 6.2). They know the standards of the genre backward and forward, and this knowledge allows them to be creative individually while collectively playing the same tune.

Figure 6.2: Jazz ensembles depend upon a common foundation to inspire improvisation while working together to form a holistic work of art. Photo by Roland Godefroy, License

Experience principles provide structure and guidelines that connect collaborators while giving them room to be innovative. As with a time signature, they ensure alignment. Similar to a melody, they provide a foundation that encourages supportive harmony. Like musical style, experience principles provide boundaries for what fits and what doesn’t.

Experience principles challenge a common issue in organizations: isolated soloists playing their own tune to the detriment of the whole ensemble. While still leaving plenty of room for individual improvisation, they ask a bunch of solo acts to be part of the band. This structure provides a foundation for continuity in the resulting customer journey, but doesn’t overengineer consistency and predictability, which might prevent delight and differentiation. Stressing this balance of designing the whole while distributing effort and ownership is a critical stance to take to engender cross-functional buy-in.

To get broad acceptance of your experience principles, you must help your colleagues and your leadership see their value. You will need to craft value propositions for your different stakeholders, educate the stakeholders on how to use experience principles, and pilot the experience principles to show how they are used in action. This typically requires crafting specific value propositions and education materials for different stakeholders to gain broad support and adoption. Piloting your experience principals on a project can also help others understand their tactical use. When approaching each stakeholder, consider these common values:

Defining good: While different channels and media have their specific best practices, experience principles provide a common set of criteria that can be applied across an entire end-to-end experience.
Decision-making filter: Throughout the process of determining what to do strategically and how to do it tactically, experience principles ensure that customers’ needs and desires are represented in the decision-making process.
Boundary constraints: Because these constraints represent the alignment of brand aspiration and customer desire, experience principles can filter out ideas or solutions that don’t reinforce this alignment.
Efficiency: Used consistently, experience principles reduce ambiguity and the resultant churn when determining what concepts should move forward and how to design them well.
Creativity inspiration: Experience principles are very effective in sparking new ideas with greater confidence that will map back to customer needs. (See Chapter 8, “Generating and Evaluating Ideas.”)
Quality control: Through the execution lifecycle, experience principles can be used to critique touchpoint designs (i.e., the parts) to ensure that they align to the greater experience (i.e., the whole).

Pitching and educating aside, your best bet for creating good experience principles that get adopted is to avoid creating them in a black box. You don’t want to spring your experience principles on your colleagues as if they were commandments from above to follow blindly. Instead, work together to craft a set of principles that everyone can follow energetically.

Identifying Draft Principles

Your research into the lives and journeys of customers will produce a large number of insights. These insights are reflective. They capture people’s current experiences—such as, their met and unmet needs, how they frame the world, and their desired outcomes. To craft useful and appropriate experience principles, you must turn these insights inside out to project what future experiences should be.

When You Can’t Do Research (Yet)
If you lack strong customer insights (and the support or time to gather them), it’s still valuable to craft experience principles with your colleagues. The process of creating them provides insight into the various criteria that people are using to make decisions. It also sheds light on what your collaborators believe are the most important customer needs to meet. While not as sound as research-driven principles, your team can align around a set of guidelines to inform and critique your collective work—and then build the case for gathering insights for creating better experience principles.

Patrick Quattlebaum

From the Bottom Up

The leap from insights to experience principles will take several iterations. While you may be able to rattle off a few candidates based on your research, it’s well worth the time to follow a more rigorous approach in which you work from the bottom (individual insights) to the top (a handful of well-crafted principles). Here’s how to get started:

Reassemble your facilitators and experience mappers, as they are closest to what you learned in your research.
Go back to the key insights that emerged from your discovery and research. These likely have been packaged in maps, models, research reports, or other artifacts. You can also go back to your raw data if needed.
Write each key insight on a sticky note. These will be used to spark a first pass at potential principles.
For each insight, have everyone take a pass individually at articulating a principle derived from just that insight. You can use sticky notes again or a quarter sheet of 8.5”’’x 11”’ (A6) template to give people a little more structure (see Figure 6.3).

Figure 6.3: A simple template to generate insight-level principles quickly.

At this stage, you should coach participants to avoid finding the perfect words or a pithy way to communicate a potential principle. Instead, focus on getting the core lesson learned from the insight and what advice you would give others to guide product or service decisions in the future. Table 6.1 shows a couple of examples of what a good first pass looks like.
At this stage, don’t be a wordsmith. Work quickly to reframe your insights from something you know (“Most people don’t want to…”) to what should be done to stay true to this insight (“Make it easy for people…”).
Work your way through all the insights until everyone has a principle for each one.

Table 6.1: From insights to draft principles
Insight	Principle
Most people don’t want to do their homework first. They want to get started and learn what they need to know when they need to know it.	Make it easy for people to dive in and collect knowledge when it’s most relevant.
Everyone believes their situation (financial, home, health) is unique and reflects their specific circumstances, even if it’s not true.	Approach people as they see themselves: unique people in unique situations.

Finding Patterns

You now have a superset of individual principles from which a handful of experience principles will emerge. Your next step is to find the patterns within them. You can use affinity mapping to identify principles that speak to a similar theme or intent. As with any clustering activity, this may take a few iterations until you feel that you have mutually exclusive categories. You can do this in just a few steps:

Select someone to be a workshop participant to present the principles one by one, explaining the intent behind each one.
Cycle through the rest of the group, combining like principles and noting where principles conflict with one another. As you cluster, the dialogue the group has is as important as where the principles end up.
Once things settle down, you and your colleagues can take a first pass at articulating a principle for each cluster. A simple half sheet (8.5” x 4.25” or A5) template can give some structure to this step. Again, don’t get too precious with every word yet. (see Figure 6.4). Get the essence down so that you and others can understand and further refine it with the other principles.
You should end up with several mutually exclusive categories with a draft principle for each.

Designing Principles as a System

No experience principle is an island. Each should be understandable and useful on its own, but together your principles should form a system. Your principles should be complementary and reinforcing. They should be able to be applied across channels and throughout your product or service development process. See the following “Experience Principles Refinement Workshop” for tips on how to critique your principles to ensure that they work together as a complete whole.

Creating a Mac Command symbol in Windows

Thu, 07 Jun 2018 08:50:38 +0000

I needed to include some Mac commands in a PowerPoint presentation, but couldn’t easily find how to create the loopy Command symbol (⌘). Google to the rescue!

The symbol is U+2318 (Unicode) or these characters (but with NO spaces) & # 8984; (HTML), or, if you’re typing in Word using a full keyboard, hold down the Alt key while you type 8984 on the numeric keypad.

Content Strategy Intersects with Technical Writing & User Advocacy

Thu, 07 Jun 2018 01:25:08 +0000

Photo by Jelleke Vanooteghem on Unsplash

What do Content Strategy and technical writing have in common? Does Content Strategy offer anything to a tech writer and users’ advocate?

I ask because a friend pointed me at the Content Strategy meetup “Talk the Talk: A Voice and Tone Summit”. The description intrigued me:

We stare and poke and swipe at machines all day. But no one wants to sound like one. Voice and tone helps keep us human, and they’re some of the most powerful tools in content design and strategy. How do you use voice and tone to stay human and connect with other humans? […] How do you create a system for making sure content creators deliver a consistent voice and tone to your customers? […] When do you need to change your tone for certain messages and audiences? And how do you do it?

Establishing and maintaining connection with your users? You have my attention. Practical advice for developing and modulating tone for different messages and audiences? Do tell. Industry professionals sharing their experience actually implementing all this? Yes please!

You’re probably familiar with the concepts and practices that drive Content Strategy because you’re a TechWhirl reader and, well, TechWhirl features “Content Strategy and Planning” in their menu. How did I miss it? Simply put, my work focus on creating user documentation never really intersected with it. Once I crossed that intersection, I had to satisfy my curiosity and to fill in the blank spaces in my knowledge with a trek deep into Silicon Valley.

Socializing at a professional meetup looks like a typical party: appetizers, small clots of people in animated conversation. The scene can be intimidating if you’re not an extrovert or if you don’t know anyone. It helps me to remember that a meetup is not a typical party: you all share an interest in the topic.

I joined a small group and introduced myself as a tech writer. This surprised everyone. Weird. I shrugged it off, but then it happened again with another group… and again. What’s going on here? Maybe we don’t have that much in common?

To be clear, everyone was welcoming and open. No one was dismissive or disrespectful. Still, I felt like I needed to explain myself, like I didn’t belong. My curiosity was now glowing white hot.

After some engaging talks and lively Q&A, I left the meetup that evening with my head swimming with ideas. I wanted to study my users and gather big piles of data on them, develop functional personas from the data, and then craft product stories for those personas. Every scrap of doc that my users touch would now reinforce and enable these product success stories.

So, yeah, I needed to know more about Content Strategy.

A quick search yielded Content Strategy Basics at usability.gov with a section “Best Practices for Creating Meaningful Content”. Sounds like a good place to start. Let’s run through the list with a tech writer’s eye and see what we can glean.

Reflect your organization’s goals and user’s needs

“You can discover your user’s needs through conducting market research, user research, and analyzing web metrics.”

Know your audience. This best practice should be familiar to any tech writer. As a young writer, professors and mentors branded these words onto my brain. However, I don’t remember anything specific and practical about how to do this “knowing”. I assumed that getting to know your users happened naturally as a function of your work.

Wow, was I naive. Is there any company that allows tech writers to consort with customers?

To compound the problem, I work in finance, a very insular business domain. Customer data is proprietary and closely guarded, often governed by strict privacy regulation. Users themselves are generally not very forthcoming, unless they have a problem. Our Support team has been my best source for my users’ perspective, their experiences, and their needs.

So how do you get to know your audience if you don’t have direct contact with them?

Content strategists have been working the problem for a while now. They’ve developed tools and metrics to gather information and to help them refine their work with what they learn about their users.

My own small experience with user metrics has been transformational. If you’re a tech writer without these Content Strategy tools and techniques, then you and your employer are missing out.

Understand how users think and speak about a subject

“Content should then be created and structured based on that. Doing this will also help you with search engine optimization (SEO).”

Another best practice straight out of the tech writer playbook. If you’re not writing with your users’ familiar concepts and terminology, you may as well be writing in a foreign language.

I learned early on to treat raw content from Product Managers and developers with suspicion. It’s not that their source was incorrect, but rather it was full of theory with little practical application and riddled with internal terminology completely unknown to our users. I remember how a salesperson once summed up their customers’ experience: “What is this crap?”

SEO sounds technical and very website-oriented, but if the “search engine” that you’re optimizing for is your user, then it gets very personal and applicable. You need to use the words and language that your users expect. If users can’t find what they’re looking for on their first try they give up. And if you already take user perspective into account as you write, you’re probably already optimizing your content.

Communicate to people in a way that they understand

“Embracing plain writing principles helps with this.”

I’m starting to feel some deep simpatico for Content Strategists. They understand that users want what they want and they want it now (or even sooner). Users will not parse your content for nuggets of meaning like panning for gold. Give your users nothing but gold.

Be useful

“By being purposeful in the content that you include, omit the needless.”

Simple. Anything that gets in the way of user success must go.

Stay up-to-date and and remain factual

“When new information becomes available, update your content or archive it.”

Erin Grace drives home this point in her column on regression testing your docs: “an outdated description of the product or a process… misleads users when they need help the most.” Betray your users with stale content and they will disengage and will not forgive you.

Be accessible to all people

“You have a responsibility to make sure that all people can access and benefit from your information.”

It doesn’t matter if you design websites or if you write docs, your content is not useful if your users can’t use it. Accessibility is an art and discipline in itself. In some cases, it’s required by law.

Be consistent

“Following style guides, both for language and design, helps people understand and learn what you are trying to communicate.”

Users build mental models from your content. You want the component pieces of their model to be as consistent as possible so that they snap together easily and reliably.

Inconsistencies in terminology, construction, and presentation, however, are like pieces of a jigsaw puzzle. Users don’t want a puzzle, they want a solution and they don’t want to work for it. They shouldn’t have to.

If you force your users to work too hard to use your doc they won’t.

Be able to be found

“Make sure that users can find your content both internally through navigation and also externally through search engines.”

As a corollary to the slogan “Docs or it didn’t happen”, you could say “If your users can’t find your doc, they can’t use it”. Docs that your users can’t find may as well not exist. Those are wasted effort. Can you afford to waste any effort in delighting your current users and attracting new ones? Adweek reported in 2014 that 81 percent of shoppers do online research before they buy. So if your management still labors under the idea that docs should remain hidden behind paywalls, maybe you should tell them “Docs or it ain’t going to happen.”

Help define the requirements for the overall site

“Content should drive design, structure, etc”

his should make tech writers happy. Writers create content. Logically, according to this Content Strategy best practice, tech writers should be intimately involved with the design, structure, etc. of the mechanisms that deliver their content to users.

If this is the case, then why have I been in the dark for so long about Content Strategy. Is it me? Have I been living and working under a rock all these years?

Show me the money

This isn’t a best practice of Content Strategy or of technical writing, but it helps me understand why I didn’t know more about Content Strategy until just recently.

Apparently, I’m not alone and my frustration is not unique to me. My pal, Neal Kaplan, the one who pointed me at that Content Strategy meetup, noted a distinct lack of attention paid to tech writing in the culture and literature of Content Strategy.

After another meetup, he spoke to a well-known presenter: “I asked [Kristina Halvorsen] why she gave no love to tech writers in her book [Content Strategy for the Web]”. Her answer? She said that “she loves working with tech writers and that we have really valuable insights… but rarely gets jobs where she does that, so almost all of her work is with marketing teams…”

Money is a significant indicator of priority. And marketing almost always gets the money.

My friend draws the conclusion that “content strategy is mainly focused on marketing, and there’s not nearly enough collaboration with tech writers, and all for financial reasons.”

This is a shame. I know that many organizations are missing out on the opportunity to delight their users with the combined efforts of the Content Strategists and technical writers that they have on staff.

So check out Content Strategy. If you have Content Strategy coworkers you don’t know yet, go introduce yourself. I’m sure you’ll find some common ground and do some useful, profitable, and beautiful things for your users.

Full transcript of Content strategy pitfalls podcast: change management

Tue, 05 Jun 2018 12:30:42 +0000

Gretyl Kinsey: Welcome to the Content Strategy Experts podcast, brought to you by Scriptorium. Since 1997, Scriptorium has helped companies manage, structure, organize and distribute content in an efficient way. In Episode 29, we continue our occasional series on content strategy pitfalls. Our focus today is change management. What are some common change management pitfalls and how might the intrepid content strategist avoid or handle them?

Gretyl Kinsey: Hello and welcome everyone to the Content Strategy Experts podcast. I’m Gretyl Kinsey.

Bill Swallow: And I’m Bill Swallow.

Gretyl Kinsey: And we’re here today, as I mentioned earlier, to talk about change management. I want to just start out by asking what is change management?

Bill Swallow: Change management is the management of change within an organization, and I know that’s a pretty circular definition, but it really boils down to just that. There are … it’s implemented many different ways, depending on the type of organization you have and how invested that company is in managing change.

Bill Swallow: You could see it in the form of purely a systems point of view or programmatic point of view, where change management is conducted very systematically or you can see it more in a soft-skills implementation where change management usually comes with coaching and HR involvement and lots of communication between different groups. It’s not to say that one approach is necessarily bad, it all comes down to making sure that what you’re doing actually is going to work for your company.

Gretyl Kinsey: Exactly. And I’ve seen plenty of examples just as a content strategist of implementations where change management has been a big factor and ones where it really hasn’t, and that’s interesting to see how it affects the way that things work as new changes are put forth. That’s what I want to kind of address next, is when you are rolling out a new content strategy in an organization, why is change management so important?

Bill Swallow: Anything you’re doing with regard to content strategy generally is going to affect somebody else in the organization, and usually in a big way. Either it’s going to change how they work, what they produce or generally, how they interact with other groups.

Bill Swallow: It could come down to workflow and processes; it could come down to new tools and systems changes, file transfers between different groups. File transfers between different systems. There are a lot of moving pieces in any kind of a content strategy implementation.

Bill Swallow: It’s important to be able to first identify what all of the changes are and not just from a content point of view, not just from a tools point of view but also taking into account how people work and how people interact in an organization before you start implementing a content strategy. These are the types of things generally you want to get your arms around in some kind of a change management process.

Gretyl Kinsey: And it’s something that you really can’t ignore when you’re putting that strategy together because if you do then what you’ll see happen is you’ll implement some kind of new tools or technologies, you’ll start some kind of new processes, but without that change management and without really thinking about how these new processes are going to affect the people who are in charge of putting them in place, then everything can really easily fall apart, and that’s something I think both of us have seen happen at least a few times.

Bill Swallow: Just a few.

Gretyl Kinsey: And that’s what I kind of want to get into next, is some examples of different change management problems that can come about. One of them is the idea of when you’ve got kind of upper level management pushing for a new strategy but they don’t communicate very well with the employees who are going to be the ones responsible for actually rolling it out and making sure that it happens.

Gretyl Kinsey: And in that situation, what you often get is a lot of resentment, a lack of understanding, and even sometimes the risk of completely having a project be stopped in its tracks because the employees who are most affected by that learning curve don’t know what they’re doing, don’t get told what they’re doing and why it matters, and then the question for them becomes, “Well, what is in this for me?”

Gretyl Kinsey: And if the answer has not been communicated well to them, then it seems like nothing, so that they don’t really have any kind of motivation to help make sure that the project is successful.

Bill Swallow: And the devil really is in the details, so if you have a top-down strategy implementation where people are just expected to make something happen, those who are actually performing the work probably have a better idea of what pieces need to come together and how things need to work.

Bill Swallow: And that strategy may need to shift, based on either their findings or their knowledge. And it’s really difficult to communicate that back up once you have the mandate coming down that change needs to happen.

Gretyl Kinsey: And that kind of gets back into the difference between a content strategy that originates from maybe kind of a top-down position rather than from the employees themselves. We’ve had some clients where the strategy began with the employees so the tech writers or maybe designers or whoever else is creating content, they know exactly what the problems are and they’ve had to struggle to communicate it up.

Gretyl Kinsey: But when we’ve had projects that kind of come the other way where they maybe are starting from the C-level position or just anyone in upper management then when you get to the stage of putting new tools in place and training, sometimes that communication gets left out and then you end up with really, really confused and frustrated employees.

Bill Swallow: Very true and there are also some pitfalls, starting from the other direction: from the employee level up. If employees are either taking it upon themselves or are charted to come up with a new strategy, whether it be for content or anything else, really, what we’re talking about here, yes, we’re talking in the terms of content strategy, but this really applies to any change that’s happening within a company.

Bill Swallow: If it’s happening from the employee-level up, there are lots of other issues, such as … the employees that are running with it might understand what problems need to be fixed, but they may only understand the problems within their immediate domain, so there may be other groups that could be affected by what they’re doing, that need to be involved.

Bill Swallow: These employees who are running with it may not know that. There are lots of other issues. It’s not to say that one approach is better than the other. Whether you’re planning your strategy and your implementation from a higher level down or an employee level up, they all have their own pitfalls. Neither one is better than the other.

Gretyl Kinsey: Right. And your point about not thinking about people in other groups or in other pieces of the organization actually brings up another example, which is whenever a change is coming from one department and they kind of roll out these changes without thinking about how it’s going to affect the work being done in other departments. This actually also relates to a recent pitfalls podcast we did about the idea of silos and this is something that I’ve seen happen before where you’ve got departments that are in these very separate silos but maybe a content strategy comes about that uncovers some sort of need for them to interact more.

Gretyl Kinsey: Or maybe they already are interacting and they don’t have a problem so much with silos but one of them suddenly just decides, we need this new system or this new tool. They don’t communicate about it with the other groups first, they just roll it out and then everyone else has to kind of scramble and re-work and fit into this new thing the one department has done.

Gretyl Kinsey: Instead of having a strategy upfront that kind of took into account how this is going to affect everything across all departments, then what they’re doing is sort of making things fit, which may not always work.

Bill Swallow: Mm-hmm (affirmative). And it might be the most brilliant strategy ever for that one department, but it could be the absolute worst idea to embrace ever from another department’s point of view or from their very real workflow knowledge.

Bill Swallow: It might be that they need to share content between the two and this one group developed an amazing, fantastic way of managing and developing and deploying their content that the other group simply cannot leverage based on what they’re doing and the technology and the workflows they have in place.

Bill Swallow: In which case, that strategy is essentially broken.

Gretyl Kinsey: Right, and I’ve seen this happen. It happens a lot of times when people are too early to pick tools and that’s a common problem we’ve seen overall with content strategy, but some of the examples I’ve seen are … for example, maybe the tech-comm department goes ahead, picks out a new CCMS and they don’t talk to marketing first and say, “Could you maybe share in this,” or “is there some need for you to kind of have content in a shared repository with us?”

Gretyl Kinsey: And then once that new CCMS is in place, that becomes a lot more difficult or maybe impossible. Another example might be a training department putting in place a new learning management system without consulting with the other groups first that may need to either extract or contribute content from their department to training and vice versa.

Bill Swallow: The issues with change management from silo to silo really doesn’t limit itself to a single company, either. You may have these problems during some kind of a merger/acquisition with another company. It may be that you have all your ducks in a rock and that company may have their ducks in a row but these ducks are in two completely different rows moving into completely different directions.

Bill Swallow: And it may be that in these companies, in both companies, you have a case where you have a bunch of silos in both that are each moving in their own direction and that just complicates the issue even further. But there are some very specific issues with dealing with mergers and acquisitions.

Bill Swallow: Even when you set aside content strategy, even when you set aside tools, implementations and other things, there’s the simple yet not simple problem of who’s going to own what from which side of the company? And in some cases, and I hate to say it, but there’s a very strong perception of one company’s going to win, one company’s going to lose, and who are going to be the winners, who are going to be the losers, and how is that going to impact the relationship that they’re going to have to have moving forward?

Gretyl Kinsey: Right, when it comes to something like a merger or an acquisition, there’s a whole other level of change management that has to happen because if you’ve got a content strategy that originates in one of the companies, and then needs to be branched out to kind of encompass the other ones, you’ve got the change management problem of rolling out that strategy, one.

Gretyl Kinsey: And then two, you’ve also got this change management of figuring out how these organizations are going to come together and work together. And often what happens is that these issues sort of coalesce at the same time, which is really, really stressful and challenging for all employees and managers and everyone involved, but a lot of times, what you’ll see happening is you’ll have some kind of merger or acquisition and then that will spark a need for some kind of content strategy where they figure out, how are we going to unify our brand? How are we going to unify our messaging and our content production under this new, single company name and company brand?

Gretyl Kinsey: It requires a very careful approach to change management when you’re dealing with something like mergers and acquisitions.

Bill Swallow: Very true, and it could even come down to technological stacks as well, where you have two different IT groups who need to consolidate, and not only do they need to worry about, “Oh gee do we,” one company’s running on a cloud-based system for all their email and file sharing and the other company is running on Exchange and SharePoint and other installed networks and then there’s the problem of being able to combine tools, this company’s using Frame Maker.

Bill Swallow: This company over here is using some flavor of XML. The Frame Maker’s all unstructured. They need to start sharing content. What do they do at that point? There are a lot of factors there and it’s not just easy to say, “Oh, well, we’ll just have people go to XML because that’s the stronger source.” Because then you start bending noses on the other side, where these people who are using Frame Maker might be very happy doing that and they might be very productive doing that and their documentation might be excellent.

Bill Swallow: You can rub people the wrong way, just by sending a mandate down, saying “Hey, your stuff is great, but unfortunately, you have to change everything.”

Gretyl Kinsey: Right, and that’s really … that’s something that I’ve personally seen happen with some of the clients I worked with where you’ve got a merger that happens and when one group or one of the kind of original organizations wins over the other one, there definitely can be some resistance and resentment that happens, and that entirely slows down content production. That’s the kind of thing that when you are facing a merger or an acquisition, it’s really great to think upfront about what all are the consequences of rolling out some kind of content strategy and especially deciding that one company is going to be the one to rule them all, so to speak.

Bill Swallow: Right, and we’ve used the terms winning and losing and control and all these other things, but it’s not about who wins the game. Yeah. It goes back to Little League and to t-ball, where it’s how you play the game.

Bill Swallow: It’s about sportsmanship. Really. It’s about being able to come together, make sure that you have some kind of successful outcome and that all parties are happy walking away.

Gretyl Kinsey: Exactly. And there’s a particular challenge as well with mergers and acquisitions I’ve seen, which is if that happens and the different companies are geographically distributed, there can also be a whole other level of change management that has to be taken into consideration because you can’t just maybe go over to … have all these companies now in one location or in one building and go face-to-face easily and kind of address these issues.

Gretyl Kinsey: It’s something that you have to be able to maybe deal with across miles, across countries, and across language barriers.

Bill Swallow: Very true. A single on-site visits or a single all-hands visit to a single location is not going to solve that. There needs to be open communication channels throughout, whether it be phone calls, email, text messages, Skype meetings, Slack channels, you name it. That conversation needs to be happening non-stop.

Gretyl Kinsey: Something that’s similar but kind of has its own set of different challenges to mergers and acquisitions is the idea of company growth or expansion or departmental reorganization. Maybe you’re not acquiring other companies but you are growing and changing, perhaps very rapidly and you need to maybe have some kind of mergers of different departments within your organization. Maybe you need to re-think your management structure and find some way to help make sure that you can scale up your processes to deal with growth.

Gretyl Kinsey: That’s another area where change management becomes really, really important because when you are rolling out some kind of content strategy and when you are putting these changes in place, if you’re already dealing with re-organization, just within the company itself and then also you’ve got these new tools and technologies that you’re learning, that can get really overwhelming for employees.

Bill Swallow: It can. And it’s really important at that point to map out all of these changes and make sure, again, everyone’s aware of what’s happening, what the new responsibilities are, how things are shifting, what new tools are coming into play, what old tools are being phased out, why that’s happening.

Bill Swallow: You know, it’s very important to get people on the same page. I wrote a blog post about this a couple weeks ago but there’s human nature to deal with and any kind of reorg, any kind of acquisition, any kind of major departmental change that is outside of the scope of just the tools and the methodology of putting things togethe

[Guest Post] Strategic TechComm: FrameMaker is XML authoring made easy – by Matt Sullivan

Tue, 05 Jun 2018 09:24:12 +0000

When you start working with truly large amounts of content, it’s nearly impossible to enforce standards, style guides, and content models. The answer to this problem is XML-based, structured content. Structured authoring also helps with things like content management, localization (translation), accessibility, searchability, and is even a requirement in the aerospace, defense, and other industries. Get an introduction to working with XML, DITA and S1000D in FrameMaker 2017 in this guest blog post by Matt Sullivan.

Content strategy pitfalls podcast: change management

Mon, 04 Jun 2018 12:30:55 +0000

The next installment in an occasional series on how to avoid pitfalls in your content strategy.

In this podcast, Gretyl Kinsey and Bill Swallow discuss common change management problems and how to make sure your content strategy accounts for them.

The Cult of the Complex

Thu, 31 May 2018 13:15:00 +0000

‘Tis a gift to be simple. Increasingly, in our line of work, ‘tis a rare gift indeed.

In an industry that extols innovation over customer satisfaction, and prefers algorithm to human judgement (forgetting that every algorithm has human bias in its DNA), perhaps it should not surprise us that toolchains have replaced know-how.

Likewise, in a field where young straight white dudes take an overwhelming majority of the jobs (including most of the management jobs) it’s perhaps to be expected that web making has lately become something of a dick measuring competition.

It was not always this way, and it needn’t stay this way. If we wish to get back to the business of quietly improving people’s lives, one thoughtful interaction at a time, we must rid ourselves of the cult of the complex. Admitting the problem is the first step in solving it.

And the div cries Mary

In 2001, more and more of us began using CSS to replace the non-semantic HTML table layouts with which we’d designed the web’s earliest sites. I soon noticed something about many of our new CSS-built sites. I especially noticed it in sites built by the era’s expert backend coders, many of whom viewed HTML and CSS as baby languages for non-developers.

In those days, whether from contempt for the deliberate, intentional (designed) limitations of HTML and CSS, or ignorance of the HTML and CSS framers’ intentions, many code jockeys who switched from table layouts to CSS wrote markup consisting chiefly of divs and spans. Where they meant list item, they wrote span. Where they meant paragraph, they wrote div. Where they meant level two headline, they wrote div or span with a classname of h2, or, avoiding even that tragicomic gesture toward document structure, wrote a div or span with verbose inline styling. Said div was followed by another, and another. They bred like locusts, stripping our content of structural meaning.

As an early adopter and promoter of CSS via my work in The Web Standards Project (kids, ask your parents), I rejoiced to see our people using the new language. But as a designer who understood, at least on a basic level, how HTML and CSS were supposed to work together, I chafed.

Cry, the beloved font tag

Everyone who wrote the kind of code I just described thought they were advancing the web merely by walking away from table layouts. They had good intentions, but their executions were flawed. My colleagues and I here at A List Apart were thus compelled to explain a few things.

Mainly, we argued that HTML consisting mostly of divs and spans and classnames was in no way better than table layouts for content discovery, accessibility, portability, reusability, or the web’s future. If you wanted to build for people and the long term, we said, then simple, structural, semantic HTML was best—each element deployed for its intended purpose. Don’t use a div when you mean a p.

This basic idea, and I use the adjective advisedly, along with other equally rudimentary and self-evident concepts, formed the basis of my 2003 book Designing With Web Standards, which the industry treated as a revelation, when it was merely common sense.

The message messes up the medium

When we divorce ideas from the conditions under which they arise, the result is dogma and misinformation—two things the internet is great at amplifying. Somehow, over the years, in front-end design conversations, the premise “don’t use a div when you mean a p” got corrupted into “divs are bad.”

A backlash in defense of divs followed this meaningless running-down of them—as if the W3C had created the div as a forbidden fruit. So, let’s be clear. No HTML element is bad. No HTML element is good. A screwdriver is neither good nor bad, unless you try to use it as a hammer. Good usage is all about appropriateness.

Divs are not bad. If no HTML5 element is better suited to an element’s purpose, divs are the best and most appropriate choice. Common sense, right? And yet.

Somehow, the two preceding simple sentences are never the takeaway from these discussions. Somehow, over the years, a vigorous defense of divs led to a defiant (or ignorant) overuse of them. In some strange way, stepping back from a meaningless rejection of divs opened the door to gaseous frameworks that abuse them.

Note: We don’t mind so much about the abuse of divs. After all, they are not living things. We are not purists. It’s the people who use the stuff we design who suffer from our uninformed or lazy over-reliance on these div-ridden gassy tools. And that suffering is what we protest. div-ridden, overbuilt frameworks stuffed with mystery meat offer the developer tremendous power, agility. But that power comes at a price your users pay: a hundred tons of stuff your project likely doesn’t need, but you force your users to download anyway. And that bloat is not the only problem. For who knows what evil lurks in someone else’s code?

Two cheers for frameworks

If you entered web design and development in the past ten years, you’ve likely learned and may rely on frameworks. Most of these are built on meaningless arrays of divs and spans—structures no better than the bad HTML we wrote in 1995, however more advanced the resulting pages may appear. And what keeps the whole monkey-works going? JavaScript, and more JavaScript. Without it, your content may not render. With it, you may deliver more services than you intended to.

There’s nothing wrong with using frameworks to quickly whip up and test product prototypes, especially if you do that testing in a non-public space. And theoretically, if you know what you’re doing, and are willing to edit out the bits your product doesn’t need, there’s nothing wrong with using a framework to launch a public site. Notice the operative phrases: if you know what you’re doing, and are willing to edit out the bits your product doesn’t need.

Alas, many new designers and developers (and even many experienced ones) feel like they can’t launch a new project without dragging in packages from NPM, or Composer, or whatever, with no sure idea what the code therein is doing. The results can be dangerous. Yet here we are, training an entire generation of developers to build and launch projects with untrusted code.

Indeed, many designers and developers I speak with would rather dance naked in public than admit to posting a site built with hand-coded, progressively enhanced HTML, CSS, and JavaScript they understand and wrote themselves. For them, it’s a matter of job security and viability. There’s almost a fear that if you haven’t mastered a dozen new frameworks and tools each year (and by mastered, I mean used), you’re slipping behind into irrelevancy. HR folks who write job descriptions listing the ten thousand tool sets you’re supposed to know backwards and forwards to qualify for a junior front-end position don’t help the situation.

CSS is not broken, and it’s not too hard

As our jerrybuilt contraptions, lashed together with fifteen layers of code we don’t understand and didn’t write ourselves, start to buckle and hiss, we blame HTML and CSS for the faults of developers. This fault-finding gives rise to ever more complex cults of specialized CSS, with internecine sniping between cults serving as part of their charm. New sects spring up, declaring CSS is broken, only to splinter as members disagree about precisely which way it’s broken, or which external technology not intended to control layout should be used to “fix” CSS. (Hint: They mostly choose JavaScript.)

Folks, CSS is not broken, and it’s not too hard. (You know what’s hard? Chasing the ever-receding taillights of the next shiny thing.) But don’t take my word for it. Check these out:

CSS Grid is here; it’s logical and fairly easy to learn. You can use it to accomplish all kinds of layouts that used to require JavaScript and frameworks, plus new kinds of layout nobody’s even tried yet. That kind of power requires some learning, but it’s good learning, the kind that stimulates creativity, and its power comes at no sacrifice of semantics, or performance, or accessibility. Which makes it web technology worth mastering.

The same cannot be said for our deluge of frameworks and alternative, JavaScript-based platforms. As a designer who used to love creating web experiences in code, I am baffled and numbed by the growing preference for complexity over simplicity. Complexity is good for convincing people they could not possibly do your job. Simplicity is good for everything else.

Keep it simple, smarty

Good communication strives for clarity. Design is its most brilliant when it appears most obvious—most simple. The question for web designers should never be how complex can we make it. But that’s what it has become. Just as, in pursuit of “delight,” we forget the true joy reliable, invisible interfaces can bring, so too, in chasing job security, do we pile on the platform requirements, forgetting that design is about solving business and customer problems … and that baseline skills never go out of fashion. As ALA’s Brandon Gregory, writing elsewhere, explains:

I talk with a lot of developers who list Angular, Ember, React, or other fancy JavaScript libraries among their technical skills. That’s great, but can you turn that mess of functions the junior developer wrote into a custom extensible object that we can use on other projects, even if we don’t have the extra room for hefty libraries? Can you code an image slider with vanilla JavaScript so we don’t have to add jQuery to an older website just for one piece of functionality? Can you tell me what recursion is and give me a real-world example?

“I interview web developers. Here’s how to impress me.”

Growing pains

There’s a lot of complexity to good design. Technical complexity. UX complexity. Challenges of content and microcopy. Performance challenges. This has never been and never will be an easy job.

Simplicity is not easy—not for us, anyway. Simplicity means doing the hard work that makes experiences appear seamless—the sweat and torture-testing and failure that eventually, with enough effort, yields experiences that seem to “just work.”

Nor, in lamenting our industry’s turn away from basic principles and resilient technologies, am I suggesting that CDNs and Git are useless. Or wishing that we could go back to FTP—although I did enjoy the early days of web design, when one designer could do it all. I’m glad I got to experience those simpler times.

But I like these times just fine. And I think you do, too. Our medium is growing up, and it remains our great privilege to help shape its future while creating great experiences for our users. Let us never forget how lucky we are, nor, in chasing the ever-shinier, lose sight of the people and purpose we serve.

New article in Simplifying Complexity: Reconstructing the absent user

Thu, 31 May 2018 07:00:00 +0000

I have a new article in my series on Simplifying Complexity. This article talks about why reconstructing the absent users is essential to creating good documentation.

Heroic Technical Writing offers More Than Heroics

Wed, 30 May 2018 00:01:24 +0000

Introduction

I have been visiting Heroic Technical Writing on and off since 2011, when the blog launched. The headline is clear enough, “Heroic Technical Writing: Advice and Insights on the Business of Technical Communication.” You know where you are and what kind of content you’ll see.

The subhead, “Dispensing unsolicited technical writing and career advice since 2011” is amusing and nice to know, but not critical, which is why it’s off to the right in much smaller type.

Like the blog I reviewed earlier (Blog Review: Docs by Design Blends Work and Life), Heroic Technical Writing offers a significant image right off the bat: Christopher Reeve as Superman in the 1978 movie, which resonates with me because Superman was one of the last movies I went to with my family before I started college.

So we have the headline “Heroic Technical Writing” and then we have a picture of a true hero, Superman. Heroic, indeed–and appeals to the inner geek in all of us.

Layout and Navigation

Blog posts start with the headline, date posted, the first paragraph, and occupy the left two-thirds of the page. The headlines link to the rest of the posts and you will find a handy “Continue reading” link at the end of the paragraph. The posts offer plenty of white space between paragraphs that are nicely sized for skimming.

A menu lays underneath the static screen grab of Superman. This menu offers:

Home: Leads you back to the Home Page.
New to This Page?: Functions as an About Me page. The author, Bart Leahy, tells us something about himself and the website. He talks about his clients, his schooling, his target audience (take a wild guess), what kinds of pieces he writes, and so forth. He also has a separate page devoted to his “heroic” theme.
Publications: He has written for Spaceflight Insider, Vice News, and Ad Astra magazine, among others. He has also contributed to books, magazines, and blogs, written speeches, and given presentations. He’s making me feel fairly un-accomplished right now!
Resume: Leahy starts by providing a link to his LinkedIn profile, his email address, and a phone number. This is followed by his resume. It is a long and accomplished one.
Writing for NASA: Love the fact that he has Superman as his main image, and that he has worked for NASA. Superman comes from outer space and flies through it regularly to help out us earthlings.

Nitty-Gritty Information

The column on the right contains the nitty-gritty information you need to learn more about Bart Leahy and the site. Scroll down to see:

Paying for This Site: Offers a convenient Donate button if you are so inclined.
Location and Availability: Offers a map of Leahy’s location (first of its kind I’ve seen), along with his office hours, and email address. Using Hotmail for your email is almost as bad as AOL. Hotmail screams archaic, but maybe his clients don’t mind.
Heroic Technical Writing on Facebook: Lists his Facebook page Heroic Technical Writing on Facebook. I am a member.
Twittering: Lists Leahy’s last three tweets and offers his Twitter handle: @SciCheerGopher.
Recent Posts: Offers the linked headers for his last five posts.
Following This Blog via Email: Enables you to enter your email address to receive his posts, along with a Follow button. Leahy also lists how many followers he has: 1,457.
Archives: You may search the posts by month. Each month shows the number of posts made.
Categories: Lists the post categories, along with the number of posts for that category. My favorites here are Business writing, Careers, Consulting, and, of course, Technical Writing. Lots more here to choose from.

This blog offers more general content about life and the business of writing and fewer specifics about, say, how to write API documentation. For instance, if Leahy has written a book and is now looking to sell it. He is using the Writer’s Market 2018 to find a buyer, and has written a blog post about it.

Do you sometimes wonder if you write too quickly? Afraid you may have missed something? You’re not alone. Here is Leahy’s advice on that.

As you struggle to find your own work-life balance, remember everyone else does too,what with the encroachment of our day jobs into our personal lives. When I was growing up, my dad’s employer had no idea where he was on his days off. Now, my own supervisor knows my mobile phone number. Not only that, but upper management stays in mobile contact with the office while on vacation, and sometimes they must take their laptops with them. Leahy has a take on this.

At my workplace, the clients who pay us the most money go to the front of the line, and their items get done first. So your own work-life battle is raging, work is piling up, and all your clients are clamoring for your attention, how do you begin making sense of it all? Well, according to Leahy, you need to prioritize.

Feel like you want to “tell it like it is” in the office? Afraid to express your opinion? As for myself, I am not paid to have an opinion, I’m paid to write, so that’s what I do. Leahy has this suggestion.

I am barely scratching the surface here. I enjoyed scrolling through this blog and picking entries to read. I invite you to do the same. Even if you’re not a technical writer, you should find something here of interest to you.

Conclusion

If you are a writer and a space fan, or if you work for a living like everyone else, you owe it to yourself to check this blog out. There is plenty to interest all. Sure, there is a NASA/Superman theme here, but this blog is more than that. Even if you don’t care that much for NASA, or if Superman doesn’t float your boat, just ignore that and come here anyway. I am following this blog in my feed reader.

Carrying the earth on our shoulders

Tue, 29 May 2018 13:18:43 +0000

At last week’s STC Summit, I attended a couple of presentations that probed the same question. It’s an old question, but it’s still a thorny one.

I used to see this guy on childhood trips to New York. Now he reminds me of my Tech Pubs colleagues.

How can we integrate content into a unified presentation when the content comes from all over the place? When different teams — communication specialists and nonspecialists — are creating content using different tools and different styles, often with different objectives in mind, how can we present it to customers as a unified whole?

Both presentations showcased successful case studies for integrating content. Both placed the Tech Pubs department at the center of the action. Yet both left me wondering why this whole thing — integrating content produced independently and content produced as part of a collaborative effort — isn’t easier.

How tech writers drive brand language

Rhyne Armstrong and Nate Wolf showed how their Tech Pubs department acts as a focal point for applying consistent branding for content across a division of Cisco Systems. My ears perked up with they described applying consistency to content that came from more than a dozen mergers and acquisitions over the past couple of years.

How tech writers support SMEs

Søren Weimann described a setup, using DitaExchange, in which field-support specialists put content into “topics” that look to them like Word templates. Weimann’s Tech Pubs department then performs its background magic to integrate, review, and apply a consistent format to the topics.

Tech Pubs at the center

In both scenarios, the Tech Pubs department provides and supports the infrastructure for creating, reviewing, storing, and publishing the content. It’s a good fit: Tech Pubs has the expertise and the motivation to take the leadership role. But does it have the time and the wherewithal?

As I prepared to write this article, I wondered what image I could use for an illustration. I quickly hit on one: Atlas carrying the earth, just as the Tech Pubs department carries the whole process for integrating content across the enterprise.

The Atlassian logo (until 2017)

I quickly realized that a company, Atlassian, had already appropriated that image for its name and (until recently) its logo. And that one of its flagship products, Confluence, is built for just the kind of integration and collaboration we’re talking about.

Here, from its corporate website, is how Atlassian describes Confluence:

Easily publish, organize, and access company information in one central location so you can help your customers help themselves….
Confluence combines the speed of creating on your own with the advantages of working together.

That sounds just like what we’re after.

So why isn’t everyone using Confluence, or a similar offering like DitaExchange? Because while the tool might be part of the answer, it’s apparently not the whole answer. (I’m not here to disparage Confluence. In fact, we use it at work, not for cross-department collaboration but for internal knowledge sharing, and it serves us well.)

The rest of the answer

If the tool doesn’t provide the whole answer, why not? I have a couple of ideas.

First, SMEs live in a different world, tools-wise, than technical communicators. Programmers, engineers, and field-support staff don’t talk about content-management systems. They talk about GitHub. They don’t want to hear about authoring systems, although most will deign to use Microsoft Word.

Marketing? They often inhabit a whole other world (or other universe).

That’s too many differences to reconcile in a one-size-fits-all solution. Although multiple teams within a company might agree on a set of tools and a workflow for collaboration, as Søren Weimann described, there’s no single solution that works for everyone.

Second, in many companies I suspect that the Tech Pubs department, even when it has the desire and the technical know-how to set up a system for collaboration, lacks the funding and the political clout to make it happen.

What do you think? What are the barriers to content integration and collaboration at an enterprise level? Is Tech Pubs the right organization to take the lead? If so, how can we do that, given the resources and the limited influence we have?

Do you have a success story for integrating and collaborating on content? If so, I’d love to hear about it.

Conference recap: STC Summit 2018

Tue, 29 May 2018 12:30:38 +0000

I’ve been working at Scriptorium for almost four years, but last week was my first opportunity to attend a conference. I spent a good amount of time on the exhibit hall floor, but I was also able to attend presentation sessions.

The most important thing was professional development.

On the exhibit floor

There were generally two types of people who came to our booth:

People who were interested in LearningDITA, or were already taking courses and wanted to thank us
People who wanted to know how DITA could help them

It was gratifying to see that all the work we’ve done on LearningDITA has been so well-received, and even better to see how people were happy to have a free resource to get started with DITA.

Of the second group, I fielded several questions about how they could make use of DITA in InDesign (something of a specialty of mine).

Notable sessions

How to Get Three Stars: What We Can Learn From Mobile Game Design

Alexandra Cata discussed how mobile games use a variety of methods to inform and guide the user through the application. With my background in game design and software QA, I’ve always been interested in how developers can use nonverbal elements like iconography or contextual highlighting to condense information for easier uptake.

Relating to Rocket Science

Joshua Santora, a real-deal NASA employee, discussed how NASA breaks down their more technical achievements for delivery to the general public. While people are interested in a rocket launch, how do you keep them engaged beyond the actual launch? This is particularly important for me, since I often need to discuss how I can achieve results for a client, but the means are technical. It can be struggle to break that down to make sure that we’re all on the same page.

The Future of Document Design in Virtual Reality

Crystal Elerson and Terry Smith delivered an interesting session on their preliminary findings in a research study that examines how users read in a physical and virtual environment. While I knew that there were reasons that publishers would use serif or sans serif fonts, I wasn’t aware that there could be a significant impact on readability. One of my more interesting courses of study in college was in linguistics and language acquisition, and this session helped me to fold what I learned there into how I could use that to help clients.

Takeaways

So much professional development.

I’ve been interested in attending a conference for a while now, and it was good to finally go to my first. I enjoyed meeting attendees and talking about what we do, and I appreciate the variety of sessions that I was able to attend.

I wouldn’t hesitate to attend another conference, and I’m looking forward to presenting at WritersUA East this coming October!

The post Conference recap: STC Summit 2018 appeared first on Scriptorium.

Online User Guide Writing Tips

Fri, 25 May 2018 08:00:00 +0000

Online user guides and manuals are absolutely convenient for users because they can be accessed easily and almost anywhere. As such, online user guides and manuals must be written appropriately to make them effective and user-friendly.

Unlike the print user guides and manuals, online manuals are often accessed via mobile devices such as smartphones and tablets. Although they aren’t restricted to such devices: learn more about the best formats to publish your help files.
So what should you consider when writing online user guides and manuals? Let’s get back to the basics.

Tags:

HTML

Help Authoring Tools

Documentation Formats

Tips & Tricks

How MadCap Flare Reignited My Technical Writing Career

Thu, 24 May 2018 15:30:54 +0000

In this post, Daniel Ferguson shares his journey as a technical writer and how MadCap Flare played a central role in getting him where he is today. This article was originally published in ISTC Communicator, Spring 2018 and the Smart …

The post How MadCap Flare Reignited My Technical Writing Career appeared first on MadBlog: The Official Technical Communications Blog for MadCap Software.

The linchpin of inspiration

Wed, 23 May 2018 13:20:35 +0000

Author and storyteller Carla Johnson, in her keynote speech at this week’s STC Summit, described how inspiration comes, not as a bolt from the blue, but from observing other people’s creative work. She warned against brand detachment disorder, in which we see another brand — maybe Disney or Apple — doing something cool but immediately dismiss it because it couldn’t possibly bear on our own company’s brand.

Carla Johnson

Instead, Carla charged us to observe what other brands are doing, distill the parts we can use, and relate those parts to our own brand and customers. Then we can generate ideas and pitch them to our bosses. Call it the inspiration process.

That’s what Rachel Sparks, Technical Director at Xenex, did. Xenex makes robot-like machines that hospitals use to disinfect areas where patients are treated. This is a very big deal, because it drastically reduces the threat posed by sepsis and other infections. When Sparks noticed that some hospitals were giving their machines whimsical names and putting Santa Claus hats on them, she saw a way to market her company’s product not as a machine but as something that touches people’s hearts.

That’s great creativity, great marketing. But is it technical communication? Did Carla get mixed up and think that she was speaking to the Society for Technical Marketing?

No. Carla knew exactly where she was.

The payload

The inspiration process (the labels say, in order, Observe – Distill – Relate – Generate – Pitch)

About halfway through her talk, Carla dropped her payload. But she did it so casually, and she moved so quickly to the next topic, that I’m afraid a lot of people might’ve missed it. People might’ve left the hall filled with creative energy, but not knowing how to carry that energy back into the office on Monday.

I chatted with Carla afterward (she graciously stayed in the exhibit area for several hours after her talk) and verified that, yes, this is what she’d said and, yes, this is the kernel of what she wanted her audience to hear.

Technical communicators are the linchpin between people, information, and technology.

In other words: We technical communicators — not the engineers or the the marketers or the salespeople — are uniquely able to make the inspiration process work. We can draw inspiration from what we see happening around us, distill it, and relate it to our own company’s brand. We’re the people who ought to be discovering new and creative ways to enhance our company’s brands.

All because we, uniquely, live at the intersection of people (think, audience), information, and technology.

Taking a vital role — and having fun

I like this. It means that technical communicators can have a vital role in making our companies succeed. It certainly means our jobs can be more fun.

But how many any of us do anything remotely like this? How many are in a position where, if we had a burst of creative inspiration, anyone would listen to us?

Carla would say to start small. If you have brand detachment disorder — if you think that the likes of Disney and Apple have nothing to do with your company’s brand — admit that that’s a problem. Confront your fear of going forward. Then move ahead, taking small steps at first, until the inspiration process becomes habit.

What do you think? Is Carla right about the unique role of technical communicators in the inspiration process? If you heard her speech, what did it say to you?

For me, I’m game to give it a try. Even if no one listens to me, I’ll have had some fun. And if they do listen — well, who knows what might happen?

Adobe TechComm Customer Experience Survey 2018

Wed, 23 May 2018 10:34:13 +0000

At Adobe, we continuously strive to give our customers the best experience. For this, we would love to hear your feedback and understand how we can improve our products and services to serve you better going forward. We are pleased to announce the launch of Adobe Tech Comm Customer Experience Survey 2018. Have your “SAY” […]

Onboarding: A College Student Discovers A List Apart

Tue, 22 May 2018 13:02:00 +0000

What would you say if I told you I just read and analyzed over 350 articles from A List Apart in less than six weeks? “You’re crazy!” might have passed through your lips. In that case, what would you say if I was doing it for a grade? Well, you might say that makes sense.

As a part of an Independent Research Study for my undergraduate degree, I wanted to fill in some of the gaps I had when it came to working with the World Wide Web. I wanted to know more about user experience and user interface design, however, I needed the most help getting to know the industry in general. Naturally, my professor directed me to A List Apart.

At first I wasn’t sure what I was going to get out of the assignment other than the credit I needed to graduate. What could one website really tell me? As I read article after article, I realized that I wasn’t just looking at a website—I was looking at a community. A community with history in which people have struggled to build the right way. One that is constantly working to be open to all. One that is always learning, always evolving, and sometimes hard to keep up with. A community that, without my realizing it, I had become a part of. For me, the web has pretty much always been there, but now that I am better acquainted with its past, I am energized to be a part of its future. Take a look at some of the articles that inspired this change in me.

A bit of history

I started in the Business section and went back as far as November 1999. What a whirlwind that was! I had no idea what people went through and the battles that they fought to make the web what it is today. Now, I don’t mean to date any of you lovely readers, but I would have been three years old when the first business article on A List Apart was published, so everything I read until about 2010 was news to me.

For instance, when I came across Jeffrey Zeldman’s “Survivor! (How Your Peers Are Coping with the Dotcom Crisis)” that was published in 2001, I had no idea what he was talking about! The literal note I wrote for that article was: “Some sh** went down in the late 1990s???” I was in the dark until I had the chance to Google it and sheepishly ask my parents.

I had the same problem with the term Web 2.0. It wasn’t until I looked it up that I realized I didn’t know what it was, because I never experienced Web 1.0 (having not had access to the internet until 2004). In that short time, the industry had completely reinvented itself before I ever had a chance to log on!

The other bit of history that surprised me was how long and hard people had to fight to get web standards and accessibility in line. In school I’ve always been taught to make my sites accessible, and that just seemed like common sense to me. I guess I now understand why I have mixed feelings about Flash.

What I learned about accessibility

Accessibility is one of the topics I took a lot of notes on. I was glad to see that although a lot of progress had been made in this area, people were still taking the time to write about and constantly make improvements to it. In Beth Raduenzel’s “A DIY Web Accessibility Blueprint,” she explains the fundamentals to remember when designing for accessibility, including considering:

keyboard users;
blind users;
color-blind users;
low-vision users;
deaf and hard-of-hearing users;
users with learning disabilities and cognitive limitations;
mobility-impaired users;
users with speech disabilities;
and users with seizure disorders.

It was nice to have someone clearly spell it out. However, the term “user” was used a lot. This distances us from the people we are supposed to be designing for. Anne Gibson feels the same way; in her article, she states that “[web] accessibility means that people can use the web.” All people. In “My Accessibility Journey: What I’ve Learned So Far,” Manuel Matuzović gives exact examples of this:

If your site takes ten seconds to load on a mobile connection, it’s not accessible.
If your site is only optimized for one browser, it’s not accessible.
If the content on your site is difficult to understand, your site isn’t accessible.

It goes beyond just people with disabilities (although they are certainly not to be discounted).

I learned a lot of tips for designing with specific people in mind. Like including WAI-ARIA in my code to benefit visually-impaired users, and checking the color contrast of my site for people with color blindness and low-vision problems. One article even inspired me to download a Sketch plugin to easily check the contrast of my designs in the future. I’m more than willing to do what I can to allow my website to be accessible to all, but I also understand that it’s not an easy feat, and I will never get it totally right.

User research and testing methods that were new to me

Nevertheless, we still keep learning. Another topic on A List Apart I desperately wanted to absorb was the countless research, testing, and development methods I came across in my readings. Every time I turn around, someone else has come up with another way of working, and I’m always trying to keep my finger in the pie.

I’m happy to report that the majority of the methods I read about I already knew about and have used in my own projects at school. I’ve been doing open interview techniques, personas, style tiles, and element collages all along, but I was surprised by how many new practices I’d come across.

The Kano Model, the Core Model, Wizard of Oz prototyping, and think-alouds were some of the methods that piqued my curiosity. Others like brand architecture research, call center log analysis, clickstream analysis, search analytics, and stakeholder reviews I’ve heard of before, but have never been given the opportunity to try.

Unattended qualitative research, A/B testing and fake-door testing are those that stood out to me. I liked that they allow you to conduct research even if you don’t have any users in front of you. I learned a lot of new terms and did a lot of research in this section. After all, it’s easy to get lost in all the jargon.

The endless amount of abbreviations

I spent a lot of my time Googling terms during this project—especially with the older articles that mentioned programs like Fireworks that aren’t really used anymore. One of my greatest fears in working with web design is that someone will ask me something and I will have no idea what they are talking about. When I was reading all the articles, I had the hardest time with the substantial amount of abbreviations I came across: AJAX, API, ARIA, ASCII, B2B, B2C, CMS, CRM, CSS, EE, GUI, HTML, IIS, IPO, JSP, MSA, RFP, ROI, RSS, SASS, SEM, SEO, SGML, SOS, SOW, SVN, and WYSIWYG, just to name a few. Did you manage to get them all? Probably not.

We don’t use abbreviations in school because they aren’t always clear and the professors know we won’t know what they mean. To a newbie like me, these abbreviations feel like a barrier. A wall that divides the veterans of the industry and those trying to enter it. I can’t imagine how the clients must feel.

It seems as if I am not alone in my frustrations. Inayaili de León says in her article “Becoming Better Communicators,” “We want people to care about design as much as we do, but how can they if we speak to them in a foreign language?” I’m training to be a designer, I’m in Design, and I had to look up almost every abbreviation listed above.

What I learned about myself

Prior to taking on this assignment, I would have been very hesitant to declare myself capable of creating digital design. To my surprise, I’m not alone. Matt Griffin thinks, “… the constant change and adjustments that come with living on the internet can feel overwhelming.” Kendra Skeene admits, “It’s a lot to keep track of, whether you’ve been working on the web for [twenty] years or only [twenty] months.”

My fear of not knowing all the fancy lingo was lessened when I read Lyza Danger Gardner’s “Never Heard of It.” She is a seasoned professional who admits to not knowing it all, so I, a soon-to-be-grad, can too. I have good foundations and Google on my side for those pesky abbreviations that keep popping up. As long as I just remember to use my brain as Dave Rupert suggests, when I go to get a job I should do just fine.

Entering the workplace

Before starting this assignment, I knew I wanted to work in digital and interaction design, but I didn’t know where. I was worried I didn’t know enough about the web to be able to design for it—that all the jobs out there would require me to know coding languages I’d never heard of before, and I’d have a hard time standing out among the crowd.

The articles I read on A List Apart supplied me with plenty of solid career advice. After reading articles written by designers, project managers, developers, marketers, writers, and more, I’ve come out with a better understanding of what kind of work I want to do. In the article “80/20 Practitioners Make Better Communicators,” Katie Kovalcin makes a good point about not forcing yourself to learn skills just because you feel the need to:

We’ve all heard the argument that designers need to code. And while that might be ideal in some cases, the point is to expand your personal spectrum of skills to be more useful to your team, whether that manifests itself in the form of design, content strategy, UX, or even project management. A strong team foundation begins by addressing gaps that need to be filled and the places where people can meet in the middle.

I already have skills that someone desperately needs. I just need to find the right fit and expand my skills from there. Brandon Gregory also feels that hiring isn’t all about technical knowledge. In his article, he says, “personality, fit with the team, communication skills, openness to change, [and] leadership potential” are just as important.

Along with solid technical fundamentals and good soft skills, it seems as if having a voice is also crucial. When I read Jeffrey Zeldman’s article “The Love You Make,” it became clear to me that if I ever wanted to get anywhere with my career, I was going to have to start writing.

Standout articles

The writers on A List Apart have opened my eyes to many new subjects and perspectives on web design. I particularly enjoyed looking through the game design lens in Graham Herrli’s “Gaming the System … and Winning.” It was one of the few articles where I copied his diagram on interaction personality types and their goals into my notebook. Another article that made me consider a new perspective was “The King vs. Pawn Game of UI Design” by Erik Kennedy. To start with one simple element and grow from there really made something click in my head.

However, I think that the interview I read between Mica McPheeters and Sara Wachter-Boettcher stuck with me the most. I actually caught myself saying “hmm” out loud as I was reading along. Sara’s point about crash-test dummies being sized to the average male completely shifted my understanding about how important user-centered design is. Like, life-or-death important. There is no excuse not to test your products or services on a variety of users if this is what’s at stake! It’s an article I’m glad I read.

Problems I’ve noticed in the industry

During the course of my project, I noticed some things about A List Apart that I was spending so much time on. Like, for example, it wasn’t until I got to the articles that were published after 2014 that I really started to understand and relate to the content; funnily enough, that was the year I started my design degree.

I also noticed that it was around this time that female writers became much more prominent on the site. Today there may be many women on A List Apart, but I must point out a lack of women of color. Shoutout to Aimee Gonzalez-Cameron for her article “Hello, My Name is <Error>,” a beautiful assertion for cultural inclusion on the web through user-centered design.

Despite the lack of representation of women of color, I was very happy to see many writers acknowledge their privilege in the industry. Thanks to Cennydd Bowles, Matt Griffin, and Rian van der Merwe for their articles. My only qualm is that the topic of privilege has only appeared on A List Apart in the last five years. Because isn’t it kinda ironic? As creators of the web we aim to allow everyone access to our content, but not everyone has access to the industry itself. Sara Wachter-Boettcher wrote an interesting article that expands on this idea, which you should read if you haven’t already. However, I won’t hold it against any of you. That’s why we are here anyway: to learn.

The takeaway

Looking back at this assignment, I’m happy to say that I did it. It was worth every second (even with the possible eye damage from reading off my computer screen for hours on end). It was worth it because I learned more than I had ever anticipated. I received an unexpected history lesson of the recent internet past. I was bombarded by an explosion of new terms and abbreviations. I learned a lot about myself and how I can possibly fit into this community. Most importantly, I came out on the other end with more confidence in myself and my abilities—which is probably the greatest graduation gift I could receive from a final project in my last year of university. Thanks for reading, and wish me luck!

Thanks

Thanks to my Interactive Design professor Michael LeBlanc for giving me this assignment and pushing me to take it further.

At the 2018 STC Summit

Tue, 22 May 2018 12:11:44 +0000

I’m writing live this week from the STC Summit. Are you here too? If so, are you finding the experience worthwhile?

Take a moment to answer the following question. Then use the Comments section to tell me why you answered as you did. (Your vote is anonymous; your comments are not.)

If you’ve been to previous Summits, tell me how this one stacks up against those.

I’ll be back in a few days with my impressions from the Summit. But first, I want to hear from you.

More dubious guidance

Tue, 22 May 2018 09:37:21 +0000

I know how this happens, I do. A tech writer is given a task to "document the product," and it turns out there isn't much to say. But telling the bosses that nope, it's ok, we don't actually need to say anything about this might be perceived as, dunno, not being cooperative. Maybe even suggesting that the writer's job isn't that important.

Anyway, today we have a couple of examples of what might result if the writer (and common sense) does not prevail. First up, we have these, um, helpful instructions that came with a compass that I own:

There must be a universe in which people buy compasses who don't already know what N, E, S, and W mean. I don't believe we live in that universe.

But even that is reasonable compared to the following, which Twitter user Alex Warren posted today:

Better keep this for future reference in case I forget what each button does pic.twitter.com/UO795hO3Xn
— Alex Warren (@alexwarren) May 22, 2018

More dubious guidance: 1, 2, 3, 4, 5, 6, 7, 8, 9

Content strategy versus human nature

Mon, 21 May 2018 12:15:13 +0000

Implementing a content strategy is tricky. Technical issues bubble up to the surface as challenges, but those issues usually have direct solutions. The real elephant in the room isn’t technology; it’s human nature.

Human nature can thwart a content strategy implementation. To succeed, you will need a solid change management plan and a shared willingness to keep yourself in check.

Tackling human nature with change management

The term “change management” often comes with a negative connotation; it’s seen as a means of correcting bad behavior. This doesn’t have to be the case.

While there may be some active opposition to working a different way, quite a bit of opposition may be subconscious. Opposition may also be an indication that new skills training is required.

Proper training is critical, and that includes clear, consistent communication about why things are changing. When opposition is voiced, favor conversation over correction. Build a mutual understanding about where the opposition is coming from, and what the goals of the new approach are. You just may discover a new content strategy requirement or a better approach to adopt.

Passive-aggressive behavior and outright refusal to change is more difficult to manage. If conversations go nowhere, then corrective action may be necessary.

Tackling human nature on a personal level

Self-checks are important when navigating change. As someone affected by change, it’s important to understand your own reactions. Ask yourself:

Why does this bother me?
What can I do to change my perception?
What can I do or what do I need to approach this better?

As a content strategist, this level of introspection is even more critical. Your implementation will undoubtedly encounter technical or workflow-based roadblocks. You may also learn of new requirements late in the game, or encounter other obstacles such as funding issues or time constraints.

These obstacles can seem daunting, and can often result in knee-jerk reactions. It’s important to keep yourself in check, take a step back, BREATHE, and think things through.

Your first instinct may be to tackle the issue head-on, or to dive into the weeds of a technical issue to figure out a solution. By taking a step back, you will allow yourself time to process the reaction and approach the issue with a clear head. You may also prevent a cascade of new issues caused by a hasty response to the issue (such as creating more work or upsetting others involved in your implementation).

Human nature is unavoidable, but it can be managed. And, you just may learn something in the process.

The post Content strategy versus human nature appeared first on Scriptorium.

Login or log in, sign up or signup? How to tell when to use one word, when two

Sat, 19 May 2018 21:07:45 +0000

When should we use one word, when should we use two, for terms like “log in”, “sign up”, “back up”, and the like? This is a hot topic among technical writers, UX writers, and any designers who use text in their products.

The question is particularly relevant in the software industry, but it affects other product areas too. For example, a gym may invite customers to an exercise class with wording like this:

We promise you a great workout

Work out with your friends and colleagues

How can we tell whether we should use one word or two?

Even if we ourselves already know the difference, how can we teach other people, like the engineers, designers, product managers, and other people who work on our product interfaces and documentation?

A presentation – a bit of fun with a serious goal

I’ve put together a presentation that explains a way to help ourselves and others decide when to use one word, when to use two. It’s a bit of fun, but with a serious goal.

You can find the presentation on SlideShare: One word or two? How to teach the difference between “login” and “log in”, and other mind-bogglingly important compound words.

This blog post contains some extracts from the presentation.

The presentation shows a couple of slides containing a few sentences. Embedded in the sentences are some strings of repeated letters, like lllll or bbbbb.

To play along, you’ll need to replace the string of letters with the terms “log in” or “back up”.

Try speaking the sentences in your head., or even saying them out loud. This is where the bit comes in about your partner needing to be in a good mood: you could even ask your partner to play along with you!

In the first slide, replace llllllll with “log in”

Here’s the first slide with letters for replacement – replace each series of lllll with “log in”. Don’t write anything down – just say the sentences in your head or out loud:

In the next slide – replace bbbbb with “back up”:

What’s the outcome?

Did you notice any pattern in the way you pronounced the words “login” and “log in”?

If you’re like me, your stress pattern in the middle sentence is different from the first and third sentences.

In the middle sentence, we give equal emphasis to both parts of the phrase: log in.

In the first and third sentences, we give greater emphasis to the first part of the phrase: login.

The stress patterns are the same for backup.

In the middle sentence, we give equal emphasis to both parts of the phrase: back up; log in.

In the first and third sentences, we give greater emphasis to the first part of the phrase: backup; login.

And it’s the middle sentence that uses two words, while the first and third use one word.

So, you can use stress patterns to decide whether to use one word or two.

That’s one way of doing things, but what’s the theory behind it?

The rules are something like this:

If the phrase is acting as a noun, use one word. This includes cases when the phrase is used to qualify another noun.
If it’s a verb, use two words.

The presentation goes into more detail and includes some sources and additional reading.

What about hyphens?

Yes, what about hyphens. I think this is my favourite slide, because it shows a pic of a Tawny Frogmouth. They’re the coolest birds ever.

I’ll leave you to read the rest in the presentation itself

The complete presentation is on SlideShare: One word or two? How to teach the difference between “login” and “log in”, and other mind-bogglingly important compound words.

(Note: This presentation is a prettified and updated version of my earlier blog post, published in April 2014. There’s a spider in that one.)

The reason I always find time to write on this blog

Fri, 18 May 2018 07:00:00 +0000

I finally realized why I write so much: because not writing tends to be deflating.

Conference Prep: Your Insider Guide to Attending MadWorld 2018

Thu, 17 May 2018 15:30:13 +0000

The MadWorld 2018 conference is approaching fast. With three full days of learning, four evening networking events, miles of coastline and an endless list of fun things to see and do in America’s Finest City — planning your days, and …

The post Conference Prep: Your Insider Guide to Attending MadWorld 2018 appeared first on MadBlog: The Official Technical Communications Blog for MadCap Software.

Full transcript of Content strategy and management consulting podcast

Wed, 16 May 2018 12:00:30 +0000

Alan Pringle: Welcome to the Content Strategy Experts podcast brought to you by Scriptorium. Since 1997, Scriptorium has helped companies manage, structure, organize and distribute content in an efficient way.

AP: In episode 28 we discuss our approach to content strategy, which draws heavily on management consulting principles.

AP: Hi everyone, I am Alan Pringle at Scriptorium Publishing and today I have Sarah O’Keefe and Bill Swallow with me.

Sarah O’Keefe: Hey everybody.

Bill Swallow: Hello.

AP: Today we want to talk about content strategy, how we practice it here at Scriptorium, and it’s relationship to management consulting. So I guess the best way to start off, let’s define what is management consulting?

SO: Management consulting is typically defined as people coming in and solving a business problem. You hear a lot about business process reorganization. You hear a lot about obnoxious consultants wandering in and telling everybody what to do, but at it’s core, the principle is that the organization has a problem of some sort and you’re trying to figure out how do you solve that problem? How do you change the business? And there’s a pretty well-defined way or pretty well-defined methodology of how you do that. You define the problem, you do some requirements analysis, you do a gap and needs analysis, and then based on that—whatever your constraints might be—you figure out a solution to the problem.

AP: And what you’ve just laid out there, how do you see that map into content strategy?

SO: In my view, content strategy is basically management consulting restricted to a focus on content heavy problems or restricted to a focus on, “How do I solve this business problem using content?”

AP: Okay. I’m going to kind of touch on the elephant in the room—or, in the recording maybe the better way to say that. Today a lot of people, especially on social media, content strategy and content marketing are very closely aligned or linked. You see it a lot. Especially with hashtags on Twitter. How do you align what you just described with this whole focus on content marketing and Bill, do you have any thoughts on that?

SO: Yeah, Bill, why don’t you take that one.

BS: By the way that was a nice switch.

BS: Content marketing really is tangent to content strategy, and a lot of what you do within content marketing does require some kind of a content strategy to execute it. But there’s a big difference between a focus on just marketing content or just tailoring content to an audience and looking at content strategy as a whole. Content strategy is there to solve a specific business problem just like Sarah had mentioned and it does follow the same exact pattern or the same exact process for getting to that solution. As a content strategist you would come onboard and first of all figure out what the business problem is and then do all of your requirements gathering. Figure out what requirements are high priority, low priority and so forth. Get that prioritization list going and then do the full gap analysis and the needs analysis, and also at that time you can also even do a content audit. Then figure out from all that information what the solution needs to look like. Then you can go forward with making that solution actually happen.

SO: I mean content marketing could be an outcome of content strategy right? I mean you go in there and you say, “Okay, strategically in order to make this work you need to have this kind of content getting posted on the website,” but that’s the content marketing of, “Here’s the editorial calendar and here are the kind of topics we need to focus on and here are the kinds of things we need to do on a consistent basis and here’s a social media strategy.” Those are all relatively small potatoes compared to the big picture question of what is your overall strategy, which is what we’re focused on.

BS: Right. With the grand scope of a content strategy you would include marketing, you would include technical documentation, support, training, even sales. And internal documentation as well. If you have internal policies and procedures that need to follow through based on what your business goals are that align with marketing content development, product development, so forth, that all ties together.

AP: Yeah, so what I’m hearing is… content marketing is a tool or a subset of a wider content strategy.

BS: It should be because in and of itself you don’t have a business goal that is defined purely by marketing.

SO: Right, so you want to expand market share or you want to recruit or go into lets say the Spanish speaking community in a particular location. That would imply you might want to think pretty carefully about delivering Spanish language content and then how are you going to do that and how are you going to work through all of that. But content marketing itself is typically these are the kinds of topics that our organization needs to focus on.

BS: Yeah, and at the same time with that same entering the market strategy, you also have product development, you also have sales positioning and you have infrastructure demands. A lot of HR, a lot of IT work that needs to happen to make all of this happen. Yes.

AP: We’ve defined content strategy and talked about it in relation to content marketing and how that’s just a part of content strategy. Let’s go a little bigger-picture and talk about process now. What is a typical content strategy process, if there is one.

SO: Well, I think for us it looks an awful lot like a typical management consulting methodology. Somebody comes to us and says, “We have a problem and we need to fix how we work with content or we need to change how we work with content to address that problem.” Problems might be things like too many people are returning our product because they can’t figure out how to use it because the product content isn’t very good. Can we bring that product return rate down and how can we do that with content? We’re getting too many support calls. They cost too much money. We need to go into new markets. We need to globalize and we’ve only been doing two or three languages but how we need 20 and our current very manual process for creating, managing, publishing content won’t scale to 30 languages.

SO: What do we do? How do we address that? The ultimate business problem is there and then you have to figure out, “Okay, how do we solve this problem? Too many people are returning the product.” Well, okay, why is that? Figure out what’s going on. Figure out what percentage of that could be addressed by better content, delivered in better ways, delivered in more obvious places so that people actually find it, solve their problem and can use the product instead of returning it. Localization, which is Bill’s expertise, is a very common driver for new content strategy, new approaches because it gets so expensive so fast if you’re inefficient.

SO: Eventually you figure out the problem. You define it clearly. And then you figure out how to solve it with your content and your content processes and then you have to figure out how to build that system or how to maybe train your writers on how to write the right kind of content that’ll get out the door that’ll then support what you’re trying to do.

AP: Sure, and where does for example return on investment fall into all of this?

BS: There are many different places where you can find a solid return. One is certainly being able to realize revenue from a new market. That’s an obvious one. Another one would be within localization savings or time to market with localized offerings. And you can go further down into the weeds and look at content reuse… So, being able to expedite content development based on smart reuse rather than copy paste, being able to further reduce localized spending by having significant reuse in there, and just having more efficiencies within your workflows for developing, managing, publishing and maintaining this content.

AP: Sure. And from my point of view, really you can, you know say you’ve got these business problems. You need a content strategy. But someone’s got to pay for it and you’re going to make that a lot more palatable if you can show or explain, “This is what we estimate we’re going to save because we’re getting this product to market this much more quickly. This much more revenue’s going to come in to offset all the costs of the analysis and of the configuring and putting that new whatever system it is in place.”

SO: Yeah, and it’s interesting because I kind of led off with… The management consulting nearly is always done by outsiders. It’s done by consultants that come in and do stuff. And the reason for that is exactly why we operate as outside consultants. It’s because you start, after a while you start to see patterns. You start to see the same problems over and over and over again and not withstanding the fact that one day we’re working with consumer electronics and the next day we’re working with medical devices and the say after that we’re working in financial services. The content problems, they actually have content problems in common despite the fact that the industry, or the products, are completely different but there are interesting patterns in terms of how the content is developed, delivered or not developed and not delivered. Things that need to be addressed and fixed and updated. The more time and expertise and experience a consultant has looking at a variety of different companies the better off we are when we then go into the next project because… I’m not saying we’ve seen it all but we’ve seen a lot.

AP: And this very much ties in the discussion that Bill and I had in the previous episode about “you are not unique” and how there a lot of commonalities in business problems, even in completely different industries. And we’ll put a link to that podcast, by the way, in the show notes so you can listen to that also if you haven’t heard that yet.

BS: Right. And there’s another aspect too and that’s bringing in a third party really gives you a fresh perspective. You can certainly have internal strategists working on things but in order to get… If you’re finding that solutions that you’re implementing are not working as you expect or that you have this creeping doubt along the way, bringing in a third party really can help you because they come in with a fresh perspective, they need to figure out what your business model is and you need to figure out, the third party also needs to figure out whether that business model actually… They can find loopholes within the model itself. If there are business goals that flatly don’t make sense or need to be redirected that’s something that perhaps an internal resource wouldn’t be able to influence. But as an outside person coming in they can offer that fresh perspective.

AP: There is also a more superficial and, frankly, not so great angle to the third party. And that is, you can have someone in house who knows exactly what the problem is and have some really good ideas on how to fix it. However, management or whoever has their hands on the money is not interested in internal, in-house voices. They want to hear it from a third party. A consultant can go in there and say virtually the same exact things someone in-house has said yet it’s going to be taken more as gospel because it’s coming from a third party. It is grossly unfair, but that is how the corporate world is a lot of the times.

SO: Yeah, the best description I’ve heard of that is that somebody said, “You know, they listen to you when your commute is on an airplane.” In other words, literally because you’ve parachuted—okay, we don’t literally parachute in—but because we literally come from another place on an airplane without using a parachute, we parachute in and we have credibility because we’re outsiders and we’ve done a lot of these projects and we’ve looked at a cross section of stuff. But like you said, more often than not there’s already somebody inside the organization that kind of has figured out the problem. They just can’t get the attention that they need or the funding that they need because either like you said, they don’t have credibility or, and this is maybe more common, they don’t know quite how to talk to executives with money.

SO: When you go to an executive and say, “We need to invest in translation memory,” and they’re like, “I don’t even… You lost me at translation memory.” They have no idea what you’re talking about but if you say to them, “There’s technology out there that will allow us to reduce the amount of new content that we’re paying for in translation,” that they understand. You have to bring it into a very generic kind of discussion and very generically business discussion as opposed to being about nerdy technical stuff which the executives, I can assure you neither understand nor care about.

AP: Well you start talking about making more money with less effort, they care about that. A lot. Talk in metrics, talk in money, that tends to get their attention. That’s usually a good way around that.

AP: And on that note, I think we’re going to wrap things up. And if you have some opinions on our definition of content strategy, and I’m sure you do, please drop us a line. You can do it through the contact form on our website or you can send email at info@scriptorium.com.

AP: Thanks everyone, and thanks Sarah and Bill.

SO: Thank you.

BS: Thanks.

AP: Thank you for listening to the Content Strategy Experts podcast brought to you by Scriptorium. For more information, please visit scriptorium.com or check the show notes for relevant links.

The post Full transcript of Content strategy and management consulting podcast appeared first on Scriptorium.

Saying, “Yes, and…?” to Leadership Opportunities

Tue, 15 May 2018 20:30:05 +0000

What If?

“Yes, and…?” is the hallmark of improv comedy. It’s also key to our growth as leaders. What if we said, “Yes, and…?” when approached about taking a leadership role in an organization?

For many of us, our first reaction to leadership requests are, “No, because…,” or perhaps, “There’s no way I can do that!” We live in an increasingly fast-paced culture with many opportunities on where to spend our time. Many of us can be quite guarded when considering external commitments. Sometimes being guarded is warranted because of our current level of obligations; sometimes we just have an automatic “No” response. We know what saying “no” provides us: security, peacefulness, free time, and a comfort zone.

Let’s look at what saying, “Yes, and…?” has done for me and what it can maybe do for you.

My “Yes, and…?” Journey

My “Yes, and…?” journey started about 10 years ago when I agreed to be Program Manager for the Rochester Chapter of the Society for Technical Communication. My role was to obtain speakers for educational events and to help set up venues. It was a reasonably small role, and I believed I could do a good job at it.

The following spring the chapter looked for volunteers to fill their election slate. When they asked me what role I was willing to take, I said anything besides Vice President. (The Vice President role includes co-chairing our regional conference and speaking in front of a large group of people. I was not interested. As an introvert, I absolutely did not fell comfortable in that role.)

When the chapter announced the election slate, I was on the ballot–as a VP candidate! Although I didn’t believe I was suited for nor competent to take that role, I didn’t want the embarrassment of withdrawing from the role or admitting I believed it was beyond me. Providentially, the chapter nominations committee saw leadership skills in me that I did not yet see within myself. I did OK in that role. I was partnered with someone who had filled the role the previous year and I was able to act as an “understudy” and not feel as though the weight of the role was too much.

The following year, the dues structure changed in the organization and most all of the current leadership left the organization. (There were other factors–retirements, moves, etc. that also impacted. their decisions.) There was no one more senior than me. I would be the next president. I became the next chapter president. It was a good year, although we had struggles without former leaders to mentor us. I attended my first Leadership Program at the STC Summit Conference in Dallas, met and engaged with other chapter leaders, and began establishing a peer network that has been invaluable to this day.

The Next Step

After my successful year as STC Rochester president, I decided I wanted to help other chapter leaders who might face the same challenge of having no leadership mentors. I joined the Community Affairs Committee and built an outreach program and team to mentor and assist other chapter and SIG (Special Interest Group) leaders. That team made a positive impact. My “Yes, and…?” was agreeing to serve and bringing my vision for a leadership outreach team to fruition.)

Today

Fast forward to today. Next week I’ll be installed as the Vice President of the Society for Technical Communication. The following year I will become President. Unlike local chapter elections where 90% of the time candidates ran opposed, this time I had an opponent (who was also a friend). I campaigned actively for the role. I ran for office because that peer network I had become part of from through the Summit Leadership Program and the leaders I had helped support, told me they needed me to run because they believed in me. They believed that I would help lead positive and potentially deep changes to the organization to address our changing demographics and to ensure we’d be a viable and influential organization in the future.

“Yes, and…?” and Me

My leadership journey has stretched me in ways I couldn’t have imagined. I’m now comfortable speaking to large groups of people. I’m able to articulate a vision of where I believe the organization needs to go. I’ve learned to build consensus and enroll others in meaningful initiatives.

I love being able to make a difference! Although I was initially tentative and doubted my ability to be a leader, I was willing. I’ve been stretched. It’s not always been comfortable.

I wouldn’t trade the journey for anything.

“Yes, and…?” and You

Please say, “Yes, and…?” when someone (perhaps me) offers you an opportunity to serve!

Will it take you out of your comfort zone? I certainly hope so. We grow through being stretched. We grow through service to others and I believe there’s no higher calling.

Serve where you’re passionate. Make a difference!

The post Saying, “Yes, and…?” to Leadership Opportunities appeared first on BenWoelk.com.

MadWorld 2018 Speaker Spotlight: Patrick Calnan on Accessibility in Documentation

Tue, 15 May 2018 15:30:26 +0000

In just three short weeks, industry professionals in technical communication and content strategy will gather in sunny San Diego for the annual MadWorld conference. The premier conference is the setting for the largest gathering of MadCap Flare users, creating an …

The post MadWorld 2018 Speaker Spotlight: Patrick Calnan on Accessibility in Documentation appeared first on MadBlog: The Official Technical Communications Blog for MadCap Software.

They’re coming! Are you coming?

Tue, 15 May 2018 13:14:26 +0000

At next week’s STC Summit I’ll present They’re Coming! Combining Teams and Cultures. If you’re coming to the Summit, I hope to see you in my session on Tuesday, May 22, at 4:00.

M&A: it’s everywhere

M&A activity has increased steadily, both in terms of sheer numbers (blue bars) and monetary value (red line). Source: IMAA

If you work for a company in almost any field, chances are good that you recently went through a merger or acquisition, or that you’ll go through one soon. Research by the Institute for Mergers, Acquisitions and Alliances (IMAA) shows that M&A activity has increased steadily over the past 30 years, in every part of the world.

They’re Coming! is about the changes in people, workflows, and tools that accompany mergers and acquisitions (M&As).

On both sides of an M&A, fear might drive people to think They’re coming! A bunch of strangers is coming to take away my job or to wreck the corporate culture I’ve enjoyed.

Successful M&As don’t happen automatically. I’ve learned firsthand that they require thoughtful planning and deliberate action.

In fact, I’ve been on both sides. In 2005, when my smallish company was acquired by a bigger one, my colleagues and I sensed that the new company had no interest in how we did our jobs, or in whether we were doing our jobs well. We never felt integrated with the larger company; we never felt like we had a voice in decision making.

Some people find change exhilarating. Some people find it terrifying.

More recently, my current employer — Extreme Networks — acquired two business units that had been spun off from rival companies. The people in those business units might’ve feared the same things I feared at my old job in 2005. But things have worked out better for them.

In my Summit session, I’ll tell you what we did to make that possible. My story will focus on a work group I led, in which we planned and carried out the migration of all three technical writing teams to a new content management system (CMS).

Here’s a summary.

What makes a successful merger

As typified by our experience with the CMS work group, we’ve been pleased with the success we’ve had in blending three teams into one. The keys have been:

Frequent, intentional communication
Active, empathetic listening
Respecting every team member’s right to know
Involving all stakeholders (read, people) in decisions about tools and workflows
Fostering unity and open communication
Establishing a sense of shared purpose by defining common goals

In my Summit session, I’ll have lots more to say. There’ll also be a brief exercise to help you create a strategy for managing a successful transition of people, workflows, and tools for any change that’s pending in your organization.

I hope to see you there!

The Slow Death of Internet Explorer and the Future of Progressive Enhancement

Tue, 15 May 2018 12:55:00 +0000

My first full-time developer job was at a small company. We didn’t have BrowserStack, so we cobbled together a makeshift device lab. Viewing a site I’d been making on a busted first-generation iPad with an outdated version of Safari, I saw a distorted, failed mess. It brought home to me a quote from Douglas Crockford, who once deemed the web “the most hostile software engineering environment imaginable.”

The “works best with Chrome” problem

Because of this difficulty, a problem has emerged. Earlier this year, a widely shared article in the Verge warned of “works best with Chrome” messages seen around the web.

Hi Larry, we apologize for the frustration. Groupon is optimized to be used on a Google Chrome browser, and while you are definitely able to use Firefox or another browser if you'd like, there can be delays when Groupon is not used through Google Chrome.
— Groupon Help U.S. (@GrouponHelpUS) November 26, 2017

Hi Rustram. We'd always recommend that you use Google Chrome to browse the site: we've optimised things for this browser. Thanks.
— Airbnb Help (@AirbnbHelp) July 12, 2016

There are more examples of this problem. In the popular messaging app Slack, voice calls work only in Chrome. In response to help requests, Slack explains its decision like this: “It requires significant effort for us to build out support and triage issues on each browser, so we’re focused on providing a great experience in Chrome.” (Emphasis mine.) Google itself has repeatedly built sites—including Google Meet, Allo, YouTube TV, Google Earth, and YouTube Studio—that block alternative browsers entirely. This is clearly a bad practice, but highlights the fact that cross-browser compatibility can be difficult and time-consuming.

The significant feature gap, though, isn’t between Chrome and everything else. Of far more significance is the increasingly gaping chasm between Internet Explorer and every other major browser. Should our development practices be hamstrung by the past? Or should we dash into the future relinquishing some users in our wake? I’ll argue for a middle ground. We can make life easier for ourselves without breaking the backward compatibility of the web.

The widening gulf

Chrome, Opera, and Firefox ship new features constantly. Edge and Safari eventually catch up. Internet Explorer, meanwhile, has been all but abandoned by Microsoft, which is attempting to push Windows users toward Edge. IE receives nothing but security updates. It’s a frustrating period for client-side developers. We read about new features but are often unable to use them—due to a single browser with a diminishing market share.

Internet Explorer’s global market share since 2013 is shown in dark blue. It now stands at just 3 percent.

Some new features are utterly trivial (caret-color!); some are for particular use cases you may never have (WebGL 2.0, Web MIDI, Web Bluetooth). Others already feel near-essential for even the simplest sites (object-fit, Grid).

A list of features supported in Chrome but unavailable in IE11, taken from caniuse.com. This is a truncated and incomplete screenshot of an extraordinarily long list.

The promise and reality of progressive enhancement

For content-driven sites, the question of browser support should never be answered with a simple yes or no. CSS and HTML were designed to be fault-tolerant. If a particular browser doesn’t support shape-outside or service workers or font-display, you can still use those features. Your website will not implode. It’ll just lack that extra stylistic flourish or performance optimization in non-supporting browsers.

Other features, such as CSS Grid, require a bit more work. Your page layout is less enhancement than necessity, and Grid has finally brought a real layout system to the web. When used with care for simple cases, Grid can gracefully fall back to older layout techniques. We could, for example, fall back to flex-wrap. Flexbox is by now a taken-for-granted feature among developers, yet even that is riddled with bugs in IE11.

.grid > * {
    width: 270px; /* no grid fallback style */
    margin-right: 30px; /* no grid fallback style */
}

@supports (display: grid) {
.grid > * {
	width: auto;
	margin-right: 0;
}
}

In the code above, I’m setting all the immediate children of the grid to have a specified width and a margin. For browsers that support Grid, I’ll use grid-gap in place of margin and define the width of the items with the grid-template-columns property. It’s not difficult, but it adds bloat and complexity if it’s repeated throughout a codebase for different layouts. As we start building entire page layouts with Grid (and eventually display: contents), providing a fallback for IE will become increasingly arduous. By using @supports for complex layout tasks, we’re effectively solving the same problem twice—using two different methods to create a similar result.

Not every feature can be used as an enhancement. Some things are imperative. People have been getting excited about CSS custom properties since 2013, but they’re still not widely used, and you can guess why: Internet Explorer doesn’t support them. Or take Shadow DOM. People have been doing conference talks about it for more than five years. It’s finally set to land in Firefox and Edge this year, and lands in Internet Explorer … at no time in the future. You can’t patch support with transpilers or polyfills or prefixes.

Users have more browsers than ever to choose from, yet IE manages to single-handedly tie us to the pre-evergreen past of the web. If developing Chrome-only websites represents one extreme of bad development practice, shackling yourself to a vestigial, obsolete, zombie browser surely represents the other.

The problem with shoehorning

Rather than eschew modern JavaScript features, polyfilling and transpiling have become the norm. ES6 is supported everywhere other than IE, yet we’re sending all browsers transpiled versions of our code. Transpilation isn’t great for performance. A single five-line async function, for example, may well transpile to twenty-five lines of code.

“I feel some guilt about the current state of affairs,” Alex Russell said of his previous role leading development of Traceur, a transpiler that predated Babel. “I see so many traces where the combination of Babel transpilation overhead and poor [webpack] foo totally sink the performance of a site. … I’m sad that we’re still playing this game.”

What you can’t transpile, you can often polyfill. Polyfill.io has become massively popular. Chrome gets sent a blank file. Ancient versions of IE receive a giant mountain of polyfills. We are sending the largest payload to those the least equipped to deal with it—people stuck on slow, old machines.

What is to be done?

Prioritize content

Cutting the mustard is a technique popularized by the front-end team at BBC News. The approach cuts the browser market in two: all browsers receive a base experience or core content. JavaScript is conditionally loaded only by the more capable browsers. Back in 2012, their dividing line was this:

if ('querySelector' in document && 'localStorage' in window && 'addEventListener' in window) {
     // load the javascript
}

Tom Maslen, then a lead developer at the BBC, explained the rationale: “Over the last few years I feel that our industry has gotten lazy because of the crazy download speeds that broadband has given us. Everyone stopped worrying about how large their web pages were and added a ton of JS libraries, CSS files, and massive images into the DOM. This has continued on to mobile platforms that don’t always have broadband speeds or hardware capacity to render complex code.”

The Guardian, meanwhile, entirely omits both JavaScript and stylesheets from Internet Explorer 8 and further back.

The Guardian navigation as seen in Internet Explorer 8. Unsophisticated yet functional.

Nature.com takes a similar approach, delivering only a very limited stylesheet to anything older than IE10.

The nature.com homepage as seen in Internet Explorer 9.

Were you to break into a museum, steal an ancient computer, and open Netscape Navigator, you could still happily view these websites. A user comes to your site for the content. They didn’t come to see a pretty gradient or a nicely rounded border-radius. They certainly didn’t come for the potentially nauseating parallax scroll animation.

Anyone who’s been developing for the web for any amount of time will have come across a browser bug. You check your new feature in every major browser and it works perfectly—except in one. Memorizing support info from caniuse.com and using progressive enhancement is no guarantee that every feature of your site will work as expected.

The W3C’s website for the CSS Working Group as viewed in the latest version of Safari.

Regardless of how perfectly formed and well-written your code, sometimes things break through no fault of your own, even in modern browsers. If you’re not actively testing your site, bugs are more likely to reach your users, unbeknownst to you. Rather than transpiling and polyfilling and hoping for the best, we can deliver what the person came for, in the most resilient, performant, and robust form possible: unadulterated HTML. No company has the resources to actively test their site on every old version of every browser. Malfunctioning JavaScript can ruin a web experience and make a simple page unusable. Rather than leaving users to a mass of polyfills and potential JavaScript errors, we give them a basic but functional experience.

Make a clean break

What could a mustard cut look like going forward? You could conduct a feature query using JavaScript to conditionally load the stylesheet, but relying on JavaScript introduces a brittleness that would be best to avoid. You can’t use @import inside an @supports block, so we’re left with media queries.

The following query will prevent the CSS file from being delivered to any version of Internet Explorer and older versions of other browsers:

<link id="mustardcut" rel="stylesheet" href="stylesheet.css" media="
    only screen,
    only all and (pointer: fine), only all and (pointer: coarse), only all and (pointer: none),
    min--moz-device-pixel-ratio:0) and (display-mode:browser), (min--moz-device-pixel-ratio:0)
">

We’re not really interested in what particular features this query is testing for; it’s just a hacky way to split between legacy and modern browsers. The shiny, modern site will be delivered to Edge, Chrome (and Chrome for Android) 39+, Opera 26+, Safari 9+, Safari on iOS 9+, and Firefox 47+. I based the query on the work of Andy Kirk. If you want to take a cutting-the-mustard approach but have to meet different support demands, he maintains a Github repo with a range of options.

We can use the same media query to conditionally load a Javascript file. This gives us one consistent dividing line between old and modern browsers:

(function() {
	var linkEl = document.getElementById('mustardcut');
	if (window.matchMedia && window.matchMedia(linkEl.media).matches) {
    	var script = document.createElement('script');
    	script.src = 'your-script.js';
    	script.async = true;
    	document.body.appendChild(script);
	}
})();

matchMedia brings the power of CSS media queries to JavaScript. The matches property is a boolean that reflects the result of the query. If the media query we defined in the link tag evaluates to true, the JavaScript file will be added to the page.

It might seem like an extreme solution. From a marketing point of view, the site no longer looks “professional” for a small amount of visitors. However, we’ve managed to improve the performance for those stuck on old technology while also opening the possibility of using the latest standards on browsers that support them. This is far from a new approach. All the way back in 2001, A List Apart stopped delivering a visual design to Netscape 4. Readership among users of that browser went up.

Front-end development is complicated at the best of times. Adding support for a technologically obsolete browser adds an inordinate amount of time and frustration to the development process. Testing becomes onerous. Bug-fixing looms large.

By making a clean break with the past, we can focus our energies on building modern sites using modern standards without leaving users stuck on antiquated browsers with an untested and possibly broken site. We save a huge amount of mental overhead. If your content has real value, it can survive without flashy embellishments. And for Internet Explorer users on Windows 10, Edge is preinstalled. The full experience is only a click away.

Internet Explorer 11 with its ever-present “Open Microsoft Edge” button.

Developers must avoid living in a bubble of MacBook Pros and superfast connections. There’s no magic bullet that enables developers to use bleeding-edge features. You may still need Autoprefixer and polyfills. If you’re planning to have a large user base in Asia and Africa, you’ll need to build a site that looks great in Opera Mini and UC Browser, which have their own limitations. You might choose a different cutoff point for now, but it will increasingly pay off, in terms of both user experience and developer experience, to make use of what the modern web has to offer.

Next Sydney Write the Docs meetup at Atlassian, July 3rd

Tue, 15 May 2018 04:29:42 +0000

We’ve just announced the next Write the Docs meetup in Sydney:

Sydney: Content strategy and more

Tuesday, Jul 3, 2018, 6:00 PM

Atlassian
341 George St, Sydney NSW 2000 Sydney, AU

3 Documentarians Attending

Join us to chat about docs – why they’re a Good Thing and how to make them even better. Tech writers, engineers, editors, product managers, more – if you’re interested in docs, you’re welcome. —————— Presenter 1: Michalina Ziemba Five steps to successful content strategy —————— More details and more presentations in the work…

Check out this Meetup →

What happens at the meetup

We currently have one speaker, Michalina, who will talk about five steps to successful content strategy.

There’ll be more speakers, and the opportunity to chat to old and new friends.

Who can attend?

If you’re interested in technical documentation, you’re welcome!

Date, time, and location

Tuesday 3 July 2018, at 6pm. We aim to finish around 7.30pm.

At the Atlassian offices, 341 George St, Sydney.

Want to air your ideas?

If you have an idea for a presentation or a lightning talk, let me know.

Podcast: content strategy and management consulting

Mon, 14 May 2018 06:00:41 +0000

Sarah O’Keefe, Bill Swallow, and Alan Pringle discuss the connections between content strategy and management consulting.

Twitter handles:

Links:

The post Podcast: content strategy and management consulting appeared first on Scriptorium.

An Introduction to the NAU Professional Writing Program

Sun, 13 May 2018 14:18:20 +0000

At some point in your career, you’re going to feel the need to explore options for the next stage in your journey. And usually, professional development through continuing education plays a role in that journey. We’ve found that many professionals look into a professional writing program for one or more of the following reasons:

They want to take their career in a new direction.
They’ve topped the salary scale in their current role or organization.
They want to grow professionally in the company of other writers.
They want to try something new, such as freelancing or teaching at a community college.
They want to feel more in control of their professional writing skills.

If any of these statements fit your current mindset, it’s time for us to chat. Call me or email me.

Erika.Konrad@nau.edu

1-928-523-9064 (Arizona time, USA)

We can even schedule an UberConference, FaceTime, or Skype session. Just email me to set it up.

As the area coordinator for the online Professional and Technical Writing Program at Northern Arizona University, I am happy to answer your questions and help you to figure out if our program might be helpful to you. Here are some common questions about our program.

I live pretty far away. Do I have to come to the NAU campus for any reason?

Not ever. We have had students join us from all over the world without setting foot on the NAU campus.

I’m not a big fan of tests. Do I have to take the GRE to get into the program?

Nope!

What’s the difference between the certificate program and the master’s degree?

The certificate: 18 credit hours of coursework (6 courses)
The master’s degree: 36 credit hours of coursework (12 courses)

All certificate courses will count toward your master’s degree if you decide to pursue the master’s.

Many people take the certificate program if they

already have a master’s degree
aren’t sure whether our master’s degree is the right fit for them
need credit hours in a hurry
don’t want to complete a capstone project

How long will it take me to finish the program?

You can finish the certificate in a year if you take two courses per semester: Summer, Fall, and Spring. Students in the MA program have up to six years to complete it, but they can petition for an extension of that time if circumstances warrant it.

Almost all of our classes are eight-weeks long, except for some shorter summer classes and our full-semester capstone course.

What if I just want to try a class or two?

No problem! You can take several courses as a “non-degree” student, and then apply those courses toward your certificate or master’s degree if you decide to continue.

Do I have to write a thesis or take a comprehensive exam for the MA?

Instead of writing a thesis, at the end of your MA Professional Writing program you will create a workplace document that demonstrates your professional and technical writing knowledge and skills. You can even work on a document that you are creating in your current workplace, which provides the ultimate in practical application.

One way to go about creating this document is to identify a workplace problem, propose a course of action to solve that problem, and design a plan to research, develop, and support the solution to the problem. Then write this up.

In the past, our students have created complete websites, grant and project proposals, white papers, training modules, and public-facing documentation to solve problems in the workplace or for their own freelance writing businesses.

What can the instructors help me learn?

Dr. Michael Collins
Managerial communication, environmental writing, hospitality writing, proposal writing, research writing.

Dr. Damian Koshnick

Usability testing, document design, teaching professional writing, research writing.

Dr. Erika Konrad

Professional editing, technical writing style, writing for digital audiences, content strategy, research writing, and she can help you work on language issues if English is not your first language.

Dr. John Rothfork

Ethics of professional writing, rhetoric & writing in professional communities, research writing, document project management, technical writing issues.

When can I start?

You can start any semester, including the summer. During fall and spring semesters, you can start either in the first or second 8-week session.

How much does it cost?

Go to this site to estimate the cost of your program: http://ec.nau.edu/AffordableTuitionRates.aspx

What about financial aid or scholarships?

NAU has two sites that help you with options for paying for tuition:

I work full time. Do I have to be online at specific times for chat sessions or anything like that?

There are no scheduled times when you have to be online. Course material is asynchronous, which means you can do coursework any time during the week or so allotted for each unit of study.

Nevertheless, you are not out there on your own. One of the hallmarks of our program is that you will interact with the instructor and fellow classmates during each learning module.

How do I apply?

To apply, visit these program pages in the NAU online catalog:

Professional Writing MA http://catalog.nau.edu/Catalog/details?plan=ENGPRWRMA&catalogYear=1516
Professional Writing Certificate http://catalog.nau.edu/Catalog/details?plan=PRFWRTCT&catalogYear=1516

I have to get back to work, but I still have more questions!

Erika.Konrad@nau.edu

928-523-9064 (Arizona time, USA)

Enhanced Collaboration, Contribution and Review with the New Cloud-based Editor in MadCap Central

Fri, 11 May 2018 16:00:02 +0000

We recently announced the new releases of MadCap Flare and MadCap Central, where we introduced new features designed to streamline collaboration between technical writers and subject matter experts. With features such as a new browser-based lightweight editor, new user types, and …

The post Enhanced Collaboration, Contribution and Review with the New Cloud-based Editor in MadCap Central appeared first on MadBlog: The Official Technical Communications Blog for MadCap Software.

[Guest Post] Slash your editing time & supercharge your content production with templates & styles – by Matt Sullivan

Fri, 11 May 2018 11:17:02 +0000

An Adobe FrameMaker template stores formatting information so that it can be applied to one or more documents to ensure consistency. Learn more about working with templates in this guest blog post by Matt Sullivan.

Stoplight -- creating a single source of truth to drive the API lifecycle

Fri, 11 May 2018 07:00:00 +0000

Stoplight provides a platform with visual modeling tools to create an OpenAPI document for your API -- without requiring you to know the OpenAPI spec details or code the spec line by line. This API specification document can act as a single source of truth that empowers the whole API lifecycle, from UX prototyping to testing, development, documentation, sales, and more.

So You Want to Write an Article?

Thu, 10 May 2018 14:30:00 +0000

So you want to write an article. Maybe you’ve got a great way of organizing your CSS, or you’re a designer who has a method of communicating really well with developers, or you have some insight into how to best use a new technology. Whatever the topic, you have insights, you’ve read the basics of finding your voice, and you’re ready to write and submit your first article for a major publication. Here’s the thing: most article submissions suck. Yours doesn’t have to be one of them.

At A List Apart, we want to see great minds in the industry write the next great articles, and you could be one of our writers. I’ve been on the editorial team here for about nine months now, and I’ve written a fair share of articles here as well. Part of what I do is review article submissions and give feedback on what’s working and what’s not. We publish different kinds of articles, but many of the submissions I see—particularly from newer writers—fall into the same traps. If you’re trying to get an article published in A List Apart or anywhere else, knowing these common mistakes can help your article’s chances of being accepted.

Keep introductions short and snappy

Did you read the introduction above? My guess is a fair share of readers skipped straight to this point. That’s pretty typical behavior, especially for articles like this one that offer several answers to one clear question. And that’s totally fine. If you’re writing, realize that some people will do the same thing. There are some things you can do to improve the chances of your intro being read, though.

Try to open with a bang. A recent article from Caroline Roberts has perhaps the best example of this I’ve ever seen: “I won an Emmy for keeping a website free of dick pics.” When I saw that in the submission, I was instantly hooked and read the whole thing. It’s hilarious, it shows she has expertise on managing content, and it shows that the topic is more involved and interesting than it may at first seem. A more straightforward introduction to the topic of content procurement would seem very boring in comparison. Your ideas are exciting, so show that right away if you can. A funny or relatable story can also be a great way to lead into an article—just keep it brief!

If you can’t open with a bang, keep it short. State the problem, maybe put something about why it matters or why you’re qualified to write about it, and get to the content as quickly as possible. If a line in your introduction does not add value to the article, delete it. There’s little room for meandering in professional articles, but there’s absolutely no room for it in introductions.

Get specific

Going back to my first article submission for A List Apart, way before I joined the team, I wanted to showcase my talent and expertise, and I thought the best way to do this was to showcase all of it in one article. I wrote an overview of professional skills for web professionals. There was some great information in there, based on my years of experience working up through the ranks and dealing with workplace drama. I was so proud when I submitted the article. It wasn’t accepted, but I got some great feedback from the editor-in-chief: get more specific.

The most effective articles I see deal with one central idea. The more disparate ideas I see in an article, the less focused and impactful the article is. There will be exceptions to this, of course, but those are rarer than articles that suffer for this. Don’t give yourself a handicap by taking an approach that fails more often than it succeeds.

Covering one idea in great detail, with research and examples to back it up, usually goes a lot further in displaying your expertise than an overview of a bunch of disparate thoughts. Truth be told, a lot of people have probably arrived at the same ideas you have. The insights you have are not as important as your evidence and eloquence in expressing them.

Can an overview article work? Actually, yes, but you need to frame it within a specific problem. One great example I saw was an overview of web accessibility (which has not been published yet). The article followed a fictional project from beginning to end, showing how each team on the project could work toward a goal of accessibility. But the idea was not just accessibility—it was how leaders and project managers could assign responsibility in regards to accessibility. It was a great submission because it began with a problem of breadth and offered a complete solution to that problem. But it only worked because it was written specifically for an audience that needed to understand the whole process. In other words, the comprehensive nature of the article was the entire point, and it stuck to that.

Keep your audience in mind

You have a viewpoint. A problem I frequently see with new submissions is forgetting that the audience also has its viewpoint. You have to know your audience and remember how the audience’s mindset matches yours—or doesn’t. In fact, you’ll probably want to state in your introduction who the intended audience is to hook the right readers. To write a successful article, you have to keep that audience in mind and write for it specifically.

A common mistake I see writers make is using an article to vent their frustrations about the people who won’t listen to them. The problem is that the audience of our publication usually agrees with the author on these points, so a rant about why he or she is right is ultimately pointless. If you’re writing for like-minded people, it’s usually best to assume the readers agree with you and then either delve into how to best accomplish what you’re writing about or give them talking points to have that conversation in their workplace. Write the kind of advice you wish you’d gotten when those frustrations first surfaced.

Another common problem is forgetting what the audience already knows—or doesn’t know. If something is common knowledge in your industry, it doesn’t need another explanation. You might link out to another explanation somewhere else just in case, but there’s no need to start from scratch when you’re trying to make a new point. At the same time, don’t assume that all your readers have the same expertise you do. I wrote an article on some higher-level object-oriented programming concepts—something many JavaScript developers are not familiar with. Rather than spend half the article giving an overview of object-oriented programming, though, I provided some links at the beginning of the article that gave a good overview. Pro tip: if you can link out to articles from the same publication you’re submitting to, publications will appreciate the free publicity.

Defining your audience can also really help with knowing their viewpoint. Many times when I see a submission with two competing ideas, they’re written for different audiences. In my article I mentioned above, I provide some links for developers who may be new to object-oriented programming, but the primary audience is developers who already have some familiarity with it and want to go deeper. Trying to cater to both audiences wouldn’t have doubled the readership—it would have reduced it by making a large part of the article less relevant to readers.

Keep it practical

I’ll admit, of all these tips, this is the one I usually struggle with the most. I’m a writer who loves ideas, and I love explaining them in great detail. While there are some readers who appreciate this, most are looking for some tangible ways to improve something. This isn’t to say that big concepts have no place in professional articles, but you need to ask why they are there. Is your five-paragraph explanation of the history of your idea necessary for the reader to make the improvements you suggest?

This became abundantly clear to me in my first submission of an article on managing ego in the workplace. I love psychology and initially included a lengthy section up-front on how our self-esteem springs from the strengths we leaned on growing up. While this fascinated me, it wasn’t right for an audience of web professionals who wanted advice on how to improve their working relationships. Based on feedback I received, I removed the section entirely and added a section on how to manage your own ego in the workplace—much more practical, and that ended up being a favorite section in the final piece.

Successful articles solve a problem. Begin with the problem—set it up in your introduction, maybe tell a little story that illustrates how this problem manifests—and then build a case for your solution. The problem should be clear to the reader very early on in the article, and the rest of the article should all be related to that problem. There is no room for meandering and pontification in a professional article. If the article is not relevant and practical, the reader will move on to something else.

The litmus test for determining the practicality of your article is to boil it down to an outline. Of course all of your writing is much more meaningful than an outline, but look at the outline. There should be several statements along the lines of “Do this,” or “Don’t do this.” You can have other statements, of course, but they should all be building toward some tangible outcome with practical steps for the reader to take to solve the problem set up in your introduction.

It’s a hard truth you have to learn as a writer that you’ll be much more in love with your ideas than your audience will. Writing professional articles is not about self-expression—it’s about helping and serving your readers. The more clear and concise the content you offer, the more your article will be read and shared.

Support what you say

Your opinions, without evidence to support them, will only get you so far. As a writer, your ideas are probably grounded in a lot of real evidence, but your readers don’t know that—you’ll have to show it. How do you show it? Write a first draft and get your ideas out. Then do another pass to look for stories, stats, and studies to support your ideas. Trying to make a point without at least one of these is at best difficult and at worst empty hype. Professionals in your industry are less interested in platitudes and more interested in results. Having some evidence for your claims goes a long way toward demonstrating your expertise and proving your point.

Going back to my first article in A List Apart, on defusing workplace drama, I had an abstract point to prove, and I needed to show that my insights meant something. My editor on that article was fantastic and asked the right questions to steer me toward demonstrating the validity of my ideas in a meaningful way. Personal stories made up the backbone of the article, and I was able to find social psychology studies to back up what I was saying. These illustrations of the ideas ended up being more impactful than the ideas themselves, and the article was very well-received in the community.

Storytelling can be an amazing way to bring your insights to life. Real accounts or fictional, well-told stories can serve to make big ideas easier to understand, and they work best when representing typical scenarios, not edge cases. If your story goes against common knowledge, readers will pick up on that instantly and you’ll probably get some nasty comments. Never use a story to prove a point that doesn’t have any other hard evidence to back it up—use stories to illustrate points or make problems more relatable. Good stories are often the most memorable parts of articles and make your ideas and assertions easier to remember.

Stats are one of the easiest ways to make a point. If you’re arguing that ignoring website accessibility can negatively impact the business, some hard numbers are going to say a lot more than stories. If there’s a good stat to prove your point, always include it, and always be on the lookout for relevant numbers. As with stories, though, you should never try to use stats to distort the truth or prove a point that doesn’t have much else to support it. Mark Twain once said, “There are three kinds of lies: lies, damned lies, and statistics.” You shouldn’t decide what to say and then scour the internet for ways to back it up. Base your ideas on the numbers, don’t base your selection of facts on your idea.

Studies, including both user experience studies and social psychology experiments, are somewhere in between stories and stats, and a lot of the same advantages and pitfalls also apply. A lot of studies can be expressed as a story—write a quick bit from the point of view of the study participant, then go back and explain what’s really going on. This can be just as engaging and memorable as a good story, but studies usually result in stats, which usually serve to make the stories significantly more authoritative. And remember to link out to the study for people who want to read more about it!

Just make sure your study wasn’t disproved by later studies. In my first article, linked above, I originally referenced a study to introduce the bystander effect, but an editor wisely pointed out that there’s actually a lot of evidence against that interpretation of the well-known study. Interpretations can change over time, especially as new information comes out. I found a later, more relevant study that illustrated the point better and was less well-known, so it made for a better story.

Kill your darlings

Early twentieth century writer and critic Arthur Quiller-Couch once said in a speech, “Whenever you feel an impulse to perpetrate a piece of exceptionally fine writing, obey it—whole-heartedly—and delete it before sending your manuscript to press. Murder your darlings.” Variants of this quote were repeated by many authors throughout the twentieth century, and it’s just as true today as when he originally said it.

What does that mean for your article? Great prose, great analogies, great stories—any bits of brilliant writing that you churn out—only mean as much as they contribute to the subject at hand. If it doesn’t contribute anything, it needs to be killed.

When getting your article ready for submission, your best friend will be the backspace or delete key on your keyboard. Before submitting, do a read-through for the express purpose of deleting whatever you can to trim down the article. Articles are not books. Brevity is a virtue, and it usually ends up being one of the most important virtues in article submissions.

Your intro should have a clear thesis so readers know what the article is about. For every bit of writing that follows it, ask if it contributes to your argument. Does it illustrate the problem or solution? Does it give the reader empathy for or understanding of the people you’re trying to help? Does it give them guidance on how to have these conversations in their workplaces? If you can’t relate a sentence back to your original thesis, it doesn’t matter how brilliant it is—it should be deleted.

Humor can be useful, but many jokes serve as little more than an aside or distraction from the main point. Don’t interrupt your train of thought with a cute joke—use a joke to make your thoughts more clear. It doesn’t matter how funny the joke is; if it doesn’t help illustrate or reinforce one of your points, it needs to go.

There are times when a picture really is worth a thousand words. Don’t go crazy with images and illustrations in your piece, but if a quick graphic is going to save you a lengthy explanation, go that route.

So what are you waiting for?

The industry needs great advice in articles, and many of you could provide that. The points I’ve delved into in this article aren’t just formalities and vague ideas; the editing team at A List Apart has weighed in, and these are problems we see often that weaken articles and make them less accessible to readers. Heeding this advice will strengthen your professional articles, whether you plan to submit to A List Apart or anywhere else. The next amazing article in A List Apart could be yours, and we hope to see you get there.

How do you know I’m telling the truth?

Wed, 09 May 2018 13:12:12 +0000

Deep in the Amazon rain forest, they do a really marvelous thing.

Have I seen it for myself? Well, no. Did I hear it from an eyewitness? No again. Truth to tell, I read about it on the internet.

The Papuri River in South America (photo: Andre Baertschi)

I need to back up and start from the beginning.

Dave Thomas, in a recent article titled The Revolution Will Have Structured Content, describes how the language of a culture will reflect whatever values the culture finds most important.

Thus, for example, “if we require Mr., which says nothing about marital status, before a man’s name but either Miss or Mrs. before a woman’s name, we are saying that the most important thing to know about that woman is her marital status.” And that’s why, over the last half-century, the use of Ms. has become prevalent.

A grammar based on evidence

Now, Thomas asks, what if a culture placed a high value on truth? Would its language evolve a grammar that would help a listener to evaluate the veracity of a given statement?

In fact, there are such languages. And there’s a name for that kind of grammar: evidentiality.

Thomas cites the language: of the Tuyuca, a small indigenous group living near the Papuri River along the Brazil-Colombia border. In the Tuyuca language, Thomas says,

There are different verb tenses for “I saw it” versus “I heard it” versus “Someone else told me” versus “I see evidence for it” versus “It is reasonable to assume so” versus “I saw it on the internet” (well, that last one might be a paraphrase).

Yes. Thomas made up the last one. But all of the others are real.

When I first read about the Tuyuca language, my mind started racing.

Just think: in a language where evidentiality is part of the grammar, every speaker is obligated to describe how they came to know something.

Every listener can hear that description and use it to form judgments.

It sounds wonderful, doesn’t it? I started to envy the Tuyuca, even though I didn’t know anything else about them.

But as my mind went on racing, it started carrying me to unexpected places. What happens, I wondered, when a speaker is dishonest? In Tuyuca society, surely there must be instances where, for example, someone pretends to be an eyewitness when in fact they only heard something secondhand.

When that happens, it seems like it would be incredibly easy for a listener to be misled — having assumed, in good faith, that the speaker was using the language appropriately.

Or is dishonesty so taboo that no one ever even thinks about fibbing? Does the language, having been shaped by the taboo, now serve to reinforce the taboo?

I don’t know enough about the Tuyuca culture to venture a guess.

But I know my culture. And I know that, yeah, my culture has dishonest speakers.

What if our language had a mechanism for reining in the dishonesty? Would it make us, as a culture, more honest? I’m skeptical that it would. And, anyway, it doesn’t matter. Our culture has already evolved a language that (per Thomas) reflects our core values.

We don’t need grammar to make us honest

Yet all is not lost. In our culture, it turns out, honest speakers already include evidentiality in their statements — even if it’s not baked into the grammar of the language. Journalists, for example, are careful to state whether their stories are based on eyewitness accounts or on secondhand reports.

In this article, I’ve told you where my information came from. Rather than conjecturing about the ways of the Tuyuca — or simply making things up — I’ve told you when I don’t know.

So our culture provides tools for honest speakers. Similarly, good listeners know how to interpret what they read and hear. They can ask questions as needed, and they can apply the tools of critical thinking to evaluate what they’re being told.

In Thomas’ words, “The way we structure content says a lot about the values we share.” If, as speakers and writers, we’re committed to honesty, we’ll give our hearers and our readers enough evidence to see for themselves.

If we’re not committed to honesty, we won’t do that. But it’s not because we can’t. It’s not because our language doesn’t give us the means to do it.

I’d love to hear what you think.

A Review of MadCap Flare 2018

Wed, 09 May 2018 10:45:00 +0000

MadCap released Flare 2018 last week. In this post, I’ll look at several of the new features that I think are most useful or have the most potential.

Side Navigation Output

The tri-pane skin has existed since 1995 and works perfectly well but it screams “online help”. MadCap’s Top Navigation, or topnav, skin, introduced several years ago, added a more webby look to Flare targets. However, topnav has some limitations compared to the tripane, primarily the fact that it’s not good for targets with long or complex TOCs.

Topnav displays the level 1 TOC heads in the upper pane so having a lot of level 1 heads means that the upper pane may use a lot of space, reducing the space available for content in the lower pane. See the image below for an (extreme) example of how the topnav uses the space in the upper pane.

Reducing the blank space on the left and right sides of the upper pane will reduce the number of lines that the TOC needs. But a long or complex TOC may still need this much space.

The next image shows what happens if the user hovers over one of the headings, in this case “Firewall Properties”.

Again, it can be hard to fit long or complex TOCs into this structure. The tripane eliminates this problem but at the cost of an old-style look and some codes that could cause trouble under HTML5. MadCap’s solution was to create a side navigation version of topnav, as shown below, first collapsed.

And then expanded, below…

It’s showing the same TOC as the topnav example, but TOC length is no longer an issue since the TOC pane can scroll.

Be aware that this skin, like topnav, assumes that the primary navigation for the target is the TOC and search. No index.

In summary, I think this skin is exactly what we’ve needed to offset topnav’s TOC space limitations and I expect it to see wide use.

Project Analysis

MadCap has offered a somewhat tangled set of project analysis options for years – a built-in report generator and a related file tag feature, a Project Analysis option (View > Project Analysis), and the separate Analyzer product.

The report generator and Analyzer product are similar; both offer 120+ reports on broken links, snippet suggestions, undefined styles, and so on. The main difference is that the report generator just creates the reports whereas the Analyzer product can actively help you act on them. Flare has also offered a little subset of the Analyzer under its Project Analysis option (View > Project Analysis).

In Flare 2018, MadCap appears to be taking steps to streamline all these options. The report generator and file tags features are still available but MadCap has added the core of the Analyzer product to Flare itself. In other words, we’ve gone from this in pre-2018 versions.

To this is Flare 2018 (with just one of the menus expanded and 44 reports in total). It’s not the full Analyzer but it’s a good start.

In summary, this should go a long way toward strengthening the analysis and management aspects of any Flare project.

Find Elements

Find Elements is a seemingly innocuous little feature that should come in handy if you have to clean up the code in legacy files. It’s available from the Home ribbon’s Find and Replace group and looks like this when first opened.

The Find What field offers the following options.

The results appear in a Find Results pane, typically at the bottom of the screen.

In summary, the most useful options, in my opinion, are inline styles, if you have to clean up legacy files, and MadCap, if you’re using Flare to create HTML files for use outside Flare, such as for a wiki, and have to find and remove Flare-specific tags in the output HTML files.

Other Interesting Features

Two in particular…

Review Workflow with MadCap Central – This new feature adds a new twist to your review workflows. If you’re a Contributor user, you’ve been able to solicit comments and new content from SMEs for years but you had to buy Contributor to do so. Now, if you’re a Central user, there’s no need to buy Contributor. Instead, you can add your SMEs to the review workflow through Central, in the cloud. Some of the benefits include multi-reviewer workflows, a simplified review-only interface, and change tracking.
Elasticsearch – This new feature adds a third search engine option to your projects in addition to MadCap’s own search and Google Search. My experience is that most users happily go for the MadCap search but a small number are looking for alternatives. For a comparison of the three types, see http://help.madcapsoftware.com/flare2018/Content/Flare/Targets/More/Setting-Up-Search-Engine.htm.

Summary

What I like:

How the Side Navigation Output allows Flare authors with long or complex TOCs to get the same benefits as topnav but without the space constraints.
How the Analysis feature adds tremendous project management and analysis control natively.
How the Find Elements feature helps authors look at the internals of their projects.
How the Central-based workflow adds a new option to Flare and continues what appears to be MadCap’s move into the cloud.

In my opinion, these features, especially the Side Navigation Output, make Flare 2018 a solid release that’s worth upgrading to.

MadWorld 2018 Speaker Spotlight: Kearsty Dunlap Schneider on Creating a Road Map for New Users

Tue, 08 May 2018 15:30:39 +0000

In just a couple of weeks, technical writers and documentation strategists will gather in San Diego for MadWorld 2018, the premier technical communication and content strategy conference. They’ll be joined by our lineup of speakers, ready to deliver their deep …

The post MadWorld 2018 Speaker Spotlight: Kearsty Dunlap Schneider on Creating a Road Map for New Users appeared first on MadBlog: The Official Technical Communications Blog for MadCap Software.

We’re Looking for People Who Love to Write

Tue, 08 May 2018 13:02:00 +0000

Here at A List Apart, we’re looking for new authors, and that means you. What should you write about? Glad you asked!

You should write about topics that keep you up at night, passions that make you the first to show up in the office each morning, ideas that matter to our community and about which you have a story to tell or an insight to share.

We’re not looking for case studies about your company or thousand-foot overviews of topics most ALA readers already know about (i.e., you don’t have to tell A List Apart readers that Sir Tim Berners-Lee invented the web). But you also don’t have to write earth-shaking manifestos or share new ways of working that will completely change the web. A good strong idea, or detailed advice about an industry best practice make excellent ALA articles.

Where we’ve been

Although A List Apart covers everything from accessible UX and product design to advanced typography and content and business strategy, the sweet spot for an A List Apart article is one that combines UI design (and design thinking) with front-end code, especially when it’s innovative. Thus our most popular article of the past ten years was Ethan Marcotte’s “Responsive Web Design”—a marriage of design and code, accessible to people with diverse backgrounds at differing levels of expertise.

In the decade-plus before that, our most popular articles were Douglas Bowman’s “Sliding Doors of CSS” and Dan Cederholm’s “Faux Columns”—again, marriages of design and code, and mostly in the nature of clever workarounds (because CSS in 2004 didn’t really let us design pages as flexibly and creatively, or even as reliably, as we wanted to).

From hacks to standards

Although clever front-end tricks like Sliding Doors, and visionary re-imaginings of the medium like Responsive Web Design, remain our most popular offerings, the magazine has offered fewer of them in recent years, focusing more on UX and strategy. To a certain extent, if a front-end technique isn’t earth-changing (i.e., isn’t more than just a technique), and if it isn’t semantic, inclusive, accessible, and progressively enhanced, we don’t care how flashy it is—it’s not for us.

The demand to create more powerful layouts was also, in a real way, satisfied by the rise of frameworks and shared libraries—another reason for us to have eased off front-end tricks (although not all frameworks and libraries are equally or in some cases even acceptably semantic, inclusive, accessible, and progressively enhanced—and, sadly, many of their users don’t know or care).

Most importantly, now that CSS is finally capable of true layout design without hacks, any responsible web design publication will want to ease off on the flow of front-end hacks, in favor of standards-based education, from basic to advanced. Why would any editor or publisher (or framework engineer, for that matter) recommend that designers use 100 pounds of fragile JavaScript when a dozen lines of stable CSS will do?

It will be interesting to see what happens to the demand for layout hack articles in Medium and web design publications and communities over the next twelve months. It will also be interesting to see what becomes of frameworks now that CSS is so capable. But that’s not our problem. Our problem is finding the best ideas for A List Apart’s readers, and working with the industry’s best old and new writers to polish those ideas to near-perfection.

After all, even more than being known for genius one-offs like Responsive Web Design and Sliding Doors of CSS, A List Apart has spent its life introducing future-friendly, user-focused design advances to this community, i.e., fighting for web standards when table layouts were the rage, fighting for web standards when Flash was the rage, pushing for real typography on the web years before Typekit was a gleam in Jeff Veen’s eye, pushing for readability in layout when most design-y websites thought single-spaced 7px Arial was plenty big enough, promoting accessible design solutions, user-focused solutions, independent content and communities, and so on.

Call to action

Great, industry-changing articles are still what we want most, whether they’re front-end, design, content, or strategy-focused. And changing the industry doesn’t have to mean inventing a totally new way of laying out pages or evaluating client content. It can also mean coming up with a compelling argument in favor of an important but embattled best practice. Or sharing an insightful story that helps those who read it be more empathetic and more ethical in their daily work.

Who will write the next 20 years of great A List Apart articles? That’s where you come in.

Publishing on A List Apart isn’t as easy-peasy as dashing off a post on your blog, but the results—and the audience—are worth it. And when you write for A List Apart, you never write alone: our industry-leading editors, technical editors, and copyeditors are ready to help you polish your best idea from good to great.

Come share with us!

[Guest Post] Making Your Life Easier – The 10 Coolest Features in Adobe FrameMaker – by Matt Sullivan

Tue, 08 May 2018 12:11:32 +0000

Make content production and publishing fun again with these 10 Adobe FrameMaker Features presented by Matt Sullivan …

Insomnia, content strategy edition

Mon, 07 May 2018 12:20:10 +0000

I usually sleep quite well, but every once in a while, sleep eludes me for no apparent reason. So there I am at 2 a.m., awake. Here are some of the things that keep my mind spinning:

Why, after 20 years, are we still introducing structured concepts? Where is the critical mass of adopters?
What will be the Next Big Thing after DITA?
Is content strategy irreparably tainted by the content marketing takeover?
How can we support more complexity and more requirements when we’re struggling to reach a reasonable baseline for product content quality?
What will my job look like in five years? Ten years?
Will marcom and tech comm ever end their feud? Or is this going to end like Romeo and Juliet?

What keeps you awake at night?

The post Insomnia, content strategy edition appeared first on Scriptorium.

Create a Unified Voice with the Content Development Guide from easyDITA

Mon, 07 May 2018 12:00:08 +0000

Growing companies often struggle to write with a unified voice, a constant challenge in a content-intensive business environment. As the team grows to handle content demands, so does the diversity of styles and voices. To ensure that you maintain a unified company voice that aligns with your brand strategy, you should take advantage of the Content Development Guide, created by Jorsek (makers of easyDITA) to help teams unify stylistic differences without sounding like robots.

easyDITA has designed its Content Development Guide with a simplified approach to serve as a great starting point for many organizations. Those who are transitioning to structured authoring or are still in the early stages of implementation will find value in this guide, on common style issues such as capitalization and punctuation, writing with a consistent voice and tone, and determining the best approach for an information model that works best for the organization.

Beyond a unified voice, a content development guide prevents common mishaps that can create chaos in your content repository. Based on their own internal experience, the team at easyDITA built its Content Development guide on three key components:

Style Guide
Information Model development
DITA-use Strategy

The upfront time investment of developing these three components pays dividends over the long-term for your company’s content management efforts. For example, an established linking strategy promotes link usage that’s consistent and easy to manage. Not establishing a linking strategy ahead of time usually results in authors using links in unmanageable ways. And that means your team then spends additional time and effort to painstakingly resolve broken links.

Because it’s a guide, rather than a set of hard and fast business rules, your team can customize the Content Development Guide to suit your marketing, content management, and customer support needs. To get started, click here to download the DITA files or the PDF document.

Blog Review: Docs by Design Blends Work and Life

Fri, 04 May 2018 20:14:56 +0000

Introduction

I must admit, I hadn’t visited Docs By Design before. The blog started in 2014, well after I began my career in technical writing, but my first taste was pleasant. Instead of a business logo, visitors are greeted by a picture of what I first thought was a seagull in the foreground flying over a slightly blurred image in the background, which I take to be the open sea. As I am usually cooped up somewhere, willingly slaving over my writing chores for the day, the image made me feel freer than usual.

As the Seagull(?) Flies

The bird is in the upper right, flying to the left, toward the page’s center. I describe it because the image is striking in world of technical writing. Usually, you might see the name of the author or the name of the blog or a logo first. This blog is a different kettle of fish. The name of the blog is in the lower left, in all caps and white lettering, which makes it easy to read in contrast with the blue of the sea. Should the heading, DOCS BY DESIGN, not be clear enough, the sub-head, “Bob Watson ponders technical writing, API documentation, and the world in general,” should help clear things up. You know the name of the blog’s author, Bob Watson, and what the blog is about. I like the word “ponders”– I don’t see it used much. To the right of the subheading is a down arrow subtly indicating where to start scrolling to where the blog officially begins. The arrow is so unobtrusive that I missed it the first time and simply scrolled down.

For those curious about the photo, read on.

Layout and Navigation

The layout is simple, easy on the eyes, and once again unusual because the graphic seems to have replaced any banner menu. Black typeface and white background. Few bells and whistles, but lots of welcome white space that add to the sense of freedom. Recent blog posts start with the date and the first couple of paragraphs, and occupy the left two-thirds of the page. The headlines linked to the remainder of the articles and you will find a handy “Continue reading” link at the end. The posts offer plenty of white space between paragraphs that are nicely sized for skimming You can navigate multi-page posts by clicking the page numbers at the bottom of each page, or by clicking the adjacent right or left arrows.

The column on the right contains the nitty-gritty information you need to learn more about Bob Watson and the site. Scroll down to see:

More Info: This contains an About Me page (this is where Watson’s contact info is listed, and he’s an assistant professor), a Publications page, and Useful Stuff, a tiny but growing list of academic and nonacademic items Watson has found useful. API documentation articles, anyone?
Tags: These include Agile documentation, Amateur radio (mixing the professional with the personal), Blogging , PhD Dissertation Study (I had no idea that measuring API documentation was a real thing), Technical writing (my favorite, of course), Terminology , Users, and User testing . I didn’t list every category for fear of boring my readers. Visit and have a look for yourself.
Archives: You are invited to search the archives by month and year. This list goes from March 2018 and reaches back to December 2014 (announcing the new blog). Each month and year pair lists the number of posts in parentheses.
Blogroll: Offers links to I’d Rather be Writing (Check out my recent review), UX Myths, WriteTheDocs Forum, and TC Myths. UX Myths and TC Myths are new to me, to be honest, so I need to visit those.
Connect: This section confuses me. Normally, a section called “Connect” lists someone’s social media accounts. But here we find links for subscribing to the blog (normal enough), links for the blog’s feed entries and comments, and a link for WordPress.org. Not sure what to make of this information. It seems like more of a Miscellaneous section.
About The Photo: Yes, the author took the picture himself and appears to be an enthusiast about photography (and amateur radio). Watson describes when he took the photo–of a brown pelican (so a bird watcher I’m not!), where he took it, and the specific gear he used to take the picture.

Conclusion

I am a latecomer to this website, but I recommend it to technical writers, anyone interested in API documentation, and amateur photography. Docs By Design gives you a plate of Bob Watson’s professional life and and a side dish of the personal. His posts focus on his own experiences in the world of API documentation and his experiments in coding, and I have added this blog to my feed reader.

Have a job-related or tech comm website you’d like me to review? Have some tips or tools to share with your fellow technical communicators, information developers, and content creators? Let’s network! Drop me a note: HelpFiles@TechWhirl.com. Follow me on Twitter, connect with me on LinkedIn, circle me on Google+, or email me at craig.cardimon@gmail.com. I enjoy connecting with others in the industry.

[Guest Post] Why FrameMaker costs less than Word – by Matt Sullivan

Fri, 04 May 2018 13:25:11 +0000

FrameMaker is better than Word for tech docs, says Matt Sullivan in his guest blog post. Why? Read yourself …

Introducing MadCap Flare 2018: Cloud-Based Editing, Elasticsearch, MadCap Analyzer Functionality, and More

Thu, 03 May 2018 15:30:21 +0000

We’re excited to announce the new release of MadCap Flare 2018, introducing a number of significant features that provide users with enhanced functionality and flexibility. In this new release, we’re empowering entire documentation teams with features such as cloud-based editing …

The post Introducing MadCap Flare 2018: Cloud-Based Editing, Elasticsearch, MadCap Analyzer Functionality, and More appeared first on MadBlog: The Official Technical Communications Blog for MadCap Software.

Priority Guides: A Content-First Alternative to Wireframes

Thu, 03 May 2018 13:07:00 +0000

No matter your role, if you’ve ever been involved in a digital design project, chances are you’re familiar with wireframes. After all, they’re among the most popular and widely used tools when designing websites, apps, dashboards, and other digital user interfaces.

But they do have their problems, and wireframes are so integrated into the accepted way of working that many don’t consider those drawbacks. That’s a shame, because the tool’s downsides can seriously undermine user-centricity. Ever lose yourself in aesthetic details when you should have been talking about content and functionality? We have!

That’s why we use an alternative that avoids the pitfalls of wireframes: the priority guide. It not only keeps our process user-centered and creates more valuable designs for our users (whether used alongside wireframes or as a direct replacement), it’s also improved team engagement, collaboration, and design workflows.

The problem with wireframes

Wikipedia appropriately defines the wireframe as “a visual guide that represents the skeletal framework of a website. … [It] depicts the page layout or arrangement of the website’s content, including interface elements and navigational systems.” In other words, wireframes are sketches that represent the potential website (or app) in a simplified way, including the placement and shape of any interface elements. They range from low-fidelity rough sketches on paper to high-fidelity colored, textual screens in a digital format.

Examples of low-fidelity (on the left) and high-fidelity (on the right) wireframes

Because of their visual nature, wireframes are great tools for sketching and exploring design ideas, as well as communicating those ideas to colleagues, clients, and stakeholders. And since they’re so easy to create and adapt with tools such as Sketch or Balsamiq, you also have something to user test early in the design process, allowing usability issues to be addressed sooner than might otherwise be possible.

But although these are all valuable characteristics of wireframes, there are also some significant downsides.

The illusion of final design

Wireframes can provide the illusion that a design is final, or at least in a late stage of completion. Regardless of how carefully you explain to clients or stakeholders that these first concepts are just early explorations and not final—maybe you even decorated them with big “DRAFT” stickers—too often they’ll still enthusiastically exclaim, “Looks good, let’s start building!”

Killing creativity and engagement

At Mirabeau, we’ve noticed that wireframes tend to kill creativity. We primarily work in multidisciplinary teams consisting of (among others) interaction (UX) designers, visual designers, front-end developers, and functional testers. But once an interaction designer has created a wireframe, it’s hard for many (we’re not saying all) visual designers to think outside the boundaries set by that wireframe and challenge the ideas it contains. As a result, the final designs almost always resemble the wireframes. Their creativity impaired, the visual designers were essentially just coloring in the wireframes.

Undermining user-centricity

As professionals, we naturally care about how something looks and is presented. So much so that we can easily lose ourselves for hours in the fine details, such as alignment, sizing, coloring, and the like, even on rough wireframes intended only for internal use. Losing time means losing focus on what’s valuable for your user: the content, the product offering, and the functionality.

Static, not responsive

A wireframe (even multiple wireframes) can’t capture the responsive behavior that is so essential to modern web design. Even though digital design tools are catching up in efficiently designing for different screen sizes (here’s hoping InVision Studio will deliver), each of the resulting wireframes is still just a static image.

Inconvenient for developers and functional testers

Developers and functional testers work with code, and a wireframe sketch or picture provides little functional information and isn’t directly translatable into code (not yet, anyway). This lack of clarity around how the design should behave can lead to developers and testers making decisions about functionality or responsiveness without input from the designer, or having to frequently check with the designer to find out if a feature is working correctly. Perhaps less of a problem for a mature team or project where there’s plenty of experience with, and knowledge of, the product, but all too often this (unnecessary) collaboration means more development work, a slower process, and wasted time.

To overcome these wireframe pitfalls, about five years ago we adopted priority guides. Our principal interaction designer, Paul Versteeg, brought the tool to Mirabeau, and we’ve been improving and fine-tuning our way of working with them ever since, with great results.

So what are priority guides?

As far as we know, credit for the invention of priority guides goes to Drew Clemens, who first introduced the concept in his article on the Smashing Magazine website in 2012. Since that time, however, it seems that priority guides have received little attention, either from the web and app design industry or within related education establishments.

Simply put, a priority guide contains content and elements for a mobile screen, sorted by hierarchy from top to bottom and without layout specifications. The hierarchy is based on relevance to users, with the content most critical to satisfying user needs and supporting user (and company) goals higher up.

The format of a priority guide is not fixed: it can be digital (we personally prefer Sketch), or it can be physical, made with paper and Post-its. Most importantly, a priority guide is automatically content-first, with a strong focus on providing best value for users.

The core structure of a priority guide

Diving a bit deeper, the following example shows the exact same page as shown in the wireframe images presented earlier in this article. It consists of the title “Book a flight,” real content (yes, even the required legal notice!), several sections of information, and annotations that explain components and functionality.

A detailed digital priority guide for an airline’s flight overview page

When comparing the content to the high-fidelity wireframe, you’ll notice that the order of the sections is not the same. The step indicator, for example, is shown at the bottom of the priority guide, as the designer decided it’s not the most important information on the page. Conversely, the most important information—flight information and prices—is now placed near the top.

Annotations are an important part of priority guides, as they provide explanations of the functionalities and page behavior, name the component types, and link the priority guide of one page to the priority guides of other pages. In this example, you can find descriptions of what happens when a user interacts with a button or link, such as opening a layover screen to display flight details or loading a a flight selection page.

The advantages of priority guides

Of course, we can debate for hours whether the creator of, or team responsible for, the above priority guide has chosen the correct priorities and functionalities, but that goes beyond the scope of this article. Instead, let’s name the main advantages that priority guides offer over wireframes.

Suitable for responsive design

Wireframes are static images, requiring multiple screenshots to cover the full spectrum from mobile to desktop. Priority guides, on the other hand, give an overview of content hierarchy regardless of screen size (assuming user goals remain the same on different devices). Ever since responsive design became standard practice within Mirabeau, priority guides have been an essential addition to our design toolkit.

Focused on solving problems and serving needs

When creating priority guides, you automatically focus on solving the users’ problems, serving their needs, and supporting them to reach their goals. The interface is always filled with content that communicates a message or helps the user. By designing content-first, you’re always focused on serving the user.

No time wasted on aesthetics and layout

There’s no need for interaction designers to waste time on aesthetics and layout in the early phases of the design process. Priority guides help avoid the focus shifting away from the content and user toward specific layout elements too early, and keep us from falling into the “designer trap” of visual perfectionism.

Facilitating visual designers’ creativity

Priority guides provide the opportunity for designers to explore extravagant ideas on how to best support and delight the user without visual boundaries set by interaction designers. Even when you’re the only designer on your team, working as both interaction and visual designer, it’s hard to move past how those first wireframes looked, even when confronted with new content.

Developers and testers get “HTML” early in the process

The structure of a priority guide is very similar to HTML, allowing the developer to start laying the groundwork for future development early on. Similarly, testers get a checklist for testing, allowing them to begin building those tests straight away. The result is early feedback on the feasibility of the designs, and we’ve found priority guides have significantly speeded up the collaborative process of design and development at Mirabeau.

How to create priority guides

There are a number of baselines and steps that we’ve found useful when creating priority guides. We’ve fine-tuned them over the years as we’ve applied this new approach to our projects, and conducted workshops explaining priority guides to the Dutch design community.

The baselines

Your priority guide should only contain real content that’s relevant to the user. Lorem ipsum, or any other type of placeholder text, doesn’t communicate how the page supports users in reaching their goals. Moreover, don’t include any layout elements when making priority guides. Instead, include only content and functionality. Remember that a priority guide is never a deliverable—it’s merely a tool to facilitate discussion among the designers, developers, testers, and stakeholders involved in the project.

Priority guides should always have a mobile format. By constraining yourself this way, you automatically think mobile-first and consider which information is most important (and so should be at the top of the screen). Also, since the menu is typically more or less the same on every screen of your website or app, we recommend leaving the menu out of your priority guide. It’ll help you focus on the screen you’re designing for, and the guide won’t be cluttered with unnecessary distractions.

Step 1: determine the goal(s)

Before jumping to the solution, it’s important to take a step back and consider why you’re making this priority guide. What is the purpose of the page? What goal or goals does the user have? And what goal or goals does the business have? The answers to these questions will both guide your user research and determine which content will add more value to users and the business, and so have higher priority.

Step 2: research and understand the user

There are many methods for user research, and the method or methods chosen will largely depend on the situation and project. However, when creating priority guides, we’ve definitely found it useful to generate personas, affinity diagrams, and experience maps to help create a visual summary of any research findings.

Step 3: determine the content topics

The aim of this stage is to use your knowledge of the user and the business to determine which specific content and topics will best support their goals in each phase of the customer journey. Experience has taught us that co-creating this content outline with users, clients, copywriters, and stakeholders can be highly beneficial. The result is a list of topics that each page should contain.

Step 4: create a high-level priority guide

Use the list of topics to create a high-level priority guide. Which is the most important topic? Place that one on the top. Which is the second most important topic? That one goes below the first. It’s a straightforward prioritization process that should be continued until all the (relevant) topics have found a place in the priority list. It’s important to question the importance of each topic, not only in comparison to other topics, but also whether the topic should really be on the page at all. And we’ve found that starting on paper definitely helps avoid focusing too much on the little visual details, which can happen if using a digital design tool (“pixel-fixing”).

A high-level priority guide for FreeBees, a fictional company

Step 5: create a detailed priority guide

Now it’s time to start adding the details. For each topic, determine the detailed, real content that will appear on the page. Also, start thinking about any functionalities the page may need. When you have multiple priority guides for multiple pages, indicate how and where these pages are connected in a sitemap format.

We often use this first schematic shape of the product to identify flows, test if the concept is complete, and determine whether the current content and priorities effectively serve users’ needs and help solve their problems. More than once it has allowed us to identify that a content plan needed to be altered to achieve the outcome we were targeting. And because priority guides are quick and easy to produce, iterating at this stage saved a lot of time and effort.

A detailed priority guide for FreeBees, a fictional company

Step 6: user testing and (further) iteration

The last (continuous) step involves testing and iterating your priority guides. Ask users what they think about the information presented in the priority guides (yes, it is possible to do usability testing with priority guides!), and gather feedback from stakeholders. The input gained from these sessions can then be used to validate and reprioritize the information, and to add or adapt functionalities, followed by further testing as needed.

Find out what works for you

Over the years we’ve seen many variations on the process described above. Some designers work entirely with paper and Post-its, while others prefer to create priority guides in a digital design tool from scratch. Some go no further than high-level priority guides, while others use detailed priority guides as a guideline for their entire project.

The key is to experiment, and take the time to find out which approach works best for you and your team. What remains important no matter your process, however, is the need to always keep the focus on user and business goals, and to continuously ask yourself what each piece of content or functionality adds to these goals.

Conclusion

For us here at Mirabeau, priority guides have become a highly efficient tool for designing user-first, content-first, and mobile-first, overcoming many of the significant pitfalls that come from relying only on wireframes. Wireframes do have their uses, and in many situations it’s valuable to be able to visualize ideas and discuss them with team members, clients, or stakeholders. Sketching concepts as wireframes to test ideas can also be useful, and sometimes we’ll even generate wireframes to gain new insights into how to improve our priority guides!

Overall, we’ve found that priority guides are more useful at the start of a project, when in the phase of defining the purpose and content of screens. Wireframes, on the other hand, are more useful for sketching and communicating ideas and visual concepts. Just don’t start with wireframes, and make sure you always stay focused on what’s important.

Thoughts on a remote Write the Docs meetup

Thu, 03 May 2018 04:32:24 +0000

On Wednesday this week, the Write the Docs (WtD) Australia group held a meetup entirely in cyberspace. Or, in the cloud, remote, virtual… whatever you’d like to call it.

When is a pet peeve more than just a pet peeve? When it drives I crazy!

Let’s re-establish “me” as a perfectly lovely word and give “myself” the boot.

We make up nouns and verbs at the drop of a hat – “Google it”, “Blog it” – and after a while these made-up verbs make it into the dictionary and, presumably, become ‘real’ words. Language is fluid and ever changing… mostly. For Emma, the “I” and “me” issue is a bit more concrete.

Emma Harding is known for her concern for the larger issues in technical communication. Read Watch Those Writing Pet Peeves if you don’t believe me. However, when a grammatical error is widespread and just plain wrong, she reckons it’s time to get together and wring our hands over a glass of wine or two.

Between gratuitous Austin references and interactive games, Emma gave us an hour of group therapy, and a grammar tune-up, in the use of “I” and “me”.

It’s a truth universally acknowledged…

…grammar follows rules. Language has to follow rules or we wouldn’t be able to communicate. Of course, the second truth universally acknowledged is “people don’t follow the rules”. Maybe they don’t know the rule, maybe they don’t care about the rule, maybe they don’t know that they learned the rule wrong.

There is some evidence to suggest that misusing “me” is, in fact, a genetic issue. That is to say, we get it from our parents, who got it from theirs. Someone along the line learned the rule and overapplied it, and then passed on the misconception. Don’t get it? How about an example…

And this is not a new thing. People, often quite literate people, have been doing this for centuries. Over 400 years ago, Shakespeare’s Bassanio says in The Merchant of Venice: “All debts are cleared between you and I.” Ben Jonson wrote the line, “Musco has been with my cousin and I all this day” in Every Man in His Humour.

Editor and linguist, James Harbeck, provides a nice analogy for what linguists think is happening:

“A verb gives its subject what’s called “nominative case” – it’s as though it gives a suitcase containing an “I” suit to the “me,” and the “me” puts it on and becomes “I.” But when a pronoun is in a compound (“you and I”), it’s as if the compound is a car holding the nouns and/or pronouns in it, and the case assigner doesn’t reach inside, it just puts the case on the roof. You have to learn to give the case to the passengers before they drive on out of your mouth or it will fall off and stay behind. A result of this is that kids who would never say “Me am going to the store” will say “My friends and me are going to the store.” They don’t give the case to the nouns in the compound.”

Of course, it almost never happens that we’re told “actually dear, it’s Sally and me.” So, many of us have been accidentally brainwashed to believe that “I” is somehow more correct than “me.” Not so.

Getting the I/me rule right

You might wonder if it really matters. After all, when you’re writing you can just look it up, and when you’re speaking nobody notices. It’s quite hard not to get a complex about it when you think about it too much. And of course, common usage changes a lot faster than grammar rules can keep up.

Emma shared her favourite quote of Kory Stamper, author of Word by Word: The Secret Life of Dictionaries:

“We think of English as a fortress to be defended, but a better analogy is to think of English as a child. We love and nurture it into being, and once it gains gross motor skills, it starts going exactly where we don’t want it to go: it heads right for the goddamned electrical sockets. We dress it in fancy clothes and tell it to behave, and it comes home with its underwear on its head and wearing someone else’s socks.”

So, what to do?

Resist the urge to compromise with “myself”

Myself (used incorrectly) is something that happens when we’re scared we’re getting the I/me rule wrong. After all, if you use “myself” instead of “I” or “me” then nobody will notice or suspect you don’t know the rule…

…and it’s true. They’ll be too busy thinking you sound funny. Or pretentious.

There is a misconception that using “myself” is correct for the formal register. But it’s not necessary and usually it’s not correct either. As a rule of thumb, assume “…and myself…” is always wrong.

Use “myself” for emphasis or to refer to the subject, and otherwise stick to “me” and “I”.

Remember the correct pronouns by saying each pronoun alone in the sentence.

One easy way is to take the “[name] and” bit out of the sentence and see if it still makes sense:

Sally and I will meet at the dock.

Who will meet at the dock? Sally will meet at the dock. I will meet at the dock. It (hopefully) won’t sound right to you to say “Me will…”

Retrain your ear!

Using a phrase correctly, against the common usage, is a matter of training your ear. But, as we’ve said, you might not know you learned the rule wrong. If you’re habitually getting the rule wrong, or hearing other people use the wrong thing (like “My friends and me are going to the store”) then you can’t trust your ear.

Another example is: “It is I.” This is technically correct, but nobody speaks this way. Because we don’t speak this way, we can’t use our ear to help us with this rule. This is a good time to discuss the difference between spoken language and written language, particularly when it comes to tests and formal papers. We speak informally but must write more formally. Frankly, if you knock on someone’s door and you’re asked, “Who is it?” you’re not going to say, “It is I” – they’ll think you’re weird.

How do you retrain your ear? Teach it to expect something different.

Recite the grammar rules out loud over and over. Print out the example sentences, stick them to the back of your loo-door and read aloud while you sit. Have family members leap out at you with pop-quiz questions.

Or, surround yourself with other writers who will also be going to great lengths to use the right thing.