This app design is pretty clear, telling the user the valid types of ID and calling for an action (to select). But it would be more clear to say “tap” than “select” since this is a phone app.
When I began looking at my writing experience from a UX perspective for a potential contract at Google, I realized that user experience permeates everything I do. It is the foundation of technical writing.
Technical writers are always asking questions about the user experience:
What does the user need to know?
What is the best way to provide the information?
What level of reading skills do they have?
What is their pre-existing experience with the subject matter?
How can we best accommodate different skill and experience levels?
How do I seamlessly provide the required info, making it findable and making sure it answers all their questions?
What is wrong with this design? What if you want to pay your Macy’s credit card statement. Would you choose “Pay Another Entity,” “Pay a Bill,” or “Pay a Business or Person”? Confusing! Frustrating! The user will likely have to try a few options before they can succeed at their desired task.
The X-factor in user experience design is one more question:
How do we make sure the user’s experience is positive and even delightful?
In my opinion, the technical writer is always the user’s advocate. We have the logical mind to think through every step the user needs to do to perform a task, and on any well-functioning software, app, or web design team, the technical writer is part of the initial design process, collaborating with other experts to find the best way to help the user succeed.
Sprinkling the Fun Flakes
If empathy, logic, and flow are missing, the user is not going to have a good experience, period. If the user can’t figure out what to do, if the app leads to a dead end, if there are no clear indicators of how to find an expected function—the user will feel frustrated and won’t have a positive experience. If the wording is unclear—or worse, badly written or offensive, as in the case of the website of one “UX design expert” I recently viewed—your product is dead in the water.
So cute words, fun graphics, and pleasing haptics are useless unless there is a solid design foundation and clean, clear language.
Technical writers have been helping provide that solid foundation for decades: creating task-focused text that is clear, concise, and useful.
We are the ideal professionals to add the X-factor and sprinkle the fun flakes into the fishbowl:
Compelling, effective language, backed by user research.
Great copy and tone of voice, conveying the brand and connecting personally to the user.
Rewards for accomplishing the tasks. We all like a treat!
Sacha showed entertaining and inspiring examples of videos that have been shot on smartphones, including Hollywood blockbuster films such as Steven Soderbergh’s “High Flying Bird” and “Unsane.” Soderbergh used innovative techniques such as being pushed in a wheelchair instead of using a dolly.
6 Key Principles of Effective Video Storytelling
Choose an opening shot that is going to hook your viewer
Use a lot of close-ups and extreme close-ups to capture detail and evoke interest
Switch camera angles frequently to keep it interesting
Bring it on home with the closing shot—a reward for the viewer, with an image to remember that finishes the story
Use sound to help establish the mood
Evoke emotions in the viewer—we remember how we feel more than what we see or hear
Here’s an example of what I learned. Technical writing “how to” made into art! IMHO! 😉
“Going to California” is a reference to a Led Zeppelin song lyric: “Took my chances on a big jet plane, never let ’em tell you that they’re all the same.” Each pair of students in the class made unique airplanes and unique videos!
Variations on a Theme – Adapting to Your Target Platform
Next I took the principles of great video storytelling and created 3 versions of a video:
Square for Instagram
This one is under 1 minute (timed for an Instagram feed), and square to display well in Instagram.
Short YouTube Version Captures Highlights
This is the length for my Another New York Love Affair art project, where each video is usually under two minutes. It captures the feel of the event, with behind-the-scenes warm-up and a flash on the audience at the beginning.
Full Length
This is the full length of the song. It’s my singing debut, and my Mom might want to see the whole thing!
For this reason, I am a major fan of MadCap Flare. I recommend this extremely robust, customizable Content Management System to all my clients when they need to output a mixture of shared and unique content to multiple audiences. The graphic design capabilities are incredible as well. I’ve replicated gorgeous designs from InDesign in MadCap Flare. And I recommend their Getting Started documentation as the gold standard for what end user documentation should be.
What Makes Outstanding Documentation?
Technical documentation must meet the needs of the audience. The best documentation enhances the user experience and is:
accurate
easy to find
easy to understand
describes the tasks the user must perform
provides solutions to those frustrating problems that make us turn to the documentation in the first place.
What’s Great About the MadCap Flare Documentation?
Text chunking makes the material easy to absorb
Navigation is excellent—easy to understand, with an easy-to-follow tree hierarchy, with concepts organized into task-based sections
Introductory material is provided in both text and video format, and the videos are very appealing and engaging
The language is simple and easy to understand, even when explaining complicated concepts
As a marketing tool, this URL makes a very complex, robust Content Management System seem non-intimidating and easy to use. For users of the software, this is a great starting point for learning basics, and even experts may return to this material for foundational concepts.
As a New York-based technical writer with more than two decades of experience writing for clients in varied industries, in locations from Vancouver to New York to Haiti to Chile, I notice universal themes—pain points that affect all of my clients, whatever their business line or type of documentation.
It’s all about the user experience (UX). If your customers and staff can’t use your product or perform their task, the result is pain and frustration!
Top 5 Technical Writing Pain Points
Here are the top 5 technical documentation pain points:
Obsolete! Existing documentation or procedures are out-of-date
Unclear! Instructions are hard to understand, so staff or customers can’t follow correct procedure
Disorganized! People can’t quickly find the information they need
Incomplete! There are no answers for the particular problem or task
Inconsistent! Procedures or instructions have been updated in one place but not another, leading to conflicting and confusing information
First Aid for Technical Writing Pain Points
Here I’ll tell you how good technical writing documentation addresses these pain points, one by one. Turn your user experience (UX) into satisfaction and delight!
One: From Obsolete to Up-to-the-Minute
Documentation quickly becomes obsolete without a plan for updating
Time takes a toll on any set of documentation, bringing changes that require updates. Consider this when you create your documentation, and use a system that will be easy to update. Of course, that train may have already left the station, in which case you need:
A Content Management System to keep track of all your source documents
A regular update process and schedule
A system for keeping track of changes, whether it’s specialized software or simply an Excel spreadsheet or an internal Wiki.
Two: From Unclear to Crystal
User testing is key to ensure your technical documentation is clear
Unreadability leading to lack of understanding is one of the biggest problems with documentation, and it usually occurs because the person who wrote the documentation knows the subject matter well but is not a skilled writer. Ways to ensure your documentation is crystal clear:
Use a simple writing style aimed at an eighth-grade reader
Explain all jargon and technical terms
Get actual users to follow the instructions and test the procedures – sounds like a no-brainer, right? But few companies actually do this!
Three: From Disorganized to Swiss Precision
Tagged and structured content is as organized as a Swiss candy shop
Disorganized, hard-to-find information is a very common problem, especially with complicated software or procedures that require lengthy documentation. If you have a thick binder of operating procedures or a stack of user guides, chances are, no one will look at them. But even a slender tome won’t help if the user can’t find the information they need.
To make your content findable:
Organize topics with clear titles and headings
Deliver content in a searchable online format so that people can quickly look up the subject
Include alternate search terms in your text or tags, so that people kind find a subject even if they don’t know the exact term that they’re looking for
Organize content by user task, not by the software menu structure.
Four: From Incomplete to Spot-On
Do you have gaps in your documentation?
Identifying gaps in the documentation is tricky, because you don’t know what you don’t know. Here are some sleuthing techniques to discover what’s missing and fill the holes:
Test the software or process rigorously, to find out what areas haven’t been documented
Make a list of all the tasks or procedures your users need to perform and correlate this to the existing content to identify gaps
Try doing the task wrong to find out what trouble-shooting tips your users will need
Again, user-test the documentation and watch where they go wrong, as well as what kinds of information they try to look up, then make sure you give them what they need!
Five: From Inconsistent to Single Source
Consistency is king!
Inconsistency is a problem that often creeps in over time as different people update the documentation set, perhaps making changes in one place but not another, or using different terminology to describe the same thing. Even different writing styles can be confusing to the end reader.
With technical writing, consistency is king! To achieve it:
Develop style and terminology guidelines, and follow them
Keep on track by having an editor or dedicated staff member oversee all updates when you have a team making changes
Use a Content Management System such as MadCap Flare to single source your text, so that a change only needs to be made in one place and it will be automatically updated throughout your documentation set.
A Cure for the Pain
An expert technical writer helps you succeed!
What is your top pain point? Do you need a remedy?
Karen Rempel, technical writing expert, to the rescue!
A good documentation specialist can solve your unique problems and create a set of documentation that meets your user needs and is easy to maintain.
The technical writer is the advocate for your user, and brings a perspective that will help you design documentation that is findable, clear, and easy to follow.
You get what you pay for. If you have a complex project, a product that is complicated to use, or procedures that are difficult to perform correctly, you need an experienced, expert technical writer. Budget for a professional, and you will save money in the long run.
Former CIO Linda Orlando, technical writing consultant Karen Rempel, and CEO Judith Erwin celebrating Orange Day at Grasshopper Bank, May 2018 (working towards getting the bank ready for the official opening, which occurred in May 2019)
It was a day of celebration yesterday, as Grasshopper Bank completed its journey from conception to implementation. Grasshopper Bank is the first new bank to open in New York City since the housing crisis of 2008. The “C-Suite” team is led by CEO Judith Erwin, and some of the top women in the banking industry are the lights guiding this financial institution. The dynamic team, composed of industry heavyweights who have over 200 years of combined experience in commercial banking and financial services, raised close to $100 million in order to obtain OCC* approval. The bank will focus on New York’s “innovation economy,” with corporate, venture capital, and start-up clients.
I played a crucial role in helping the new bank obtain approval from the Office of the Comptroller of the Currency (OCC) and make it to the starting line. I developed over 50 required standard operating procedures, working with various roles across the bank to determine procedures that would guide staff to perform all daily operations tasks in compliance with federal banking regulations. I brought my expertise in T24 to the task, and helped develop and document software requirements as well as procedures. My role included business analysis and training as well as technical writing, and I helped the team learn end-to-end processes for all daily and monthly procedures, from taking a deposit and boarding a loan to generating a financial statement.
I worked closely with the Chief Risk Officer, Sally Myers, to develop the required procedures to provide oversight from a risk mitigation and compliance perspective. I worked with CFO Sangeeta Kishore to ensure that the Operations team provided all required data and reports to her desk in a timely manner.
It was an exhilarating challenge and a great deal of fun, working with a fantastic team of people in an extremely dynamic, fast-paced environment. My daily compadres were the Operations team, under COO Gary Blumenthal, and it was a real pleasure to work with this group to ensure they would be able to perform all required tasks on day one.
We focused on the user experience (UX) to ensure that staff and customers will love using the bank’s internal and external banking tools, developed for mobile and the web. The team of T24 consultants under Nikki Nelson were amazing to work with, and they were instrumental in bringing the bank to the point of opening the doors yesterday.
I wish the wonderful folks at Grasshopper Bank every success as they open their doors for business. Mazel tov!
*The OCC is an independent bureau within the United States Department of the Treasury that was established by the National Currency Act of 1863 and serves to charter, regulate, and supervise all national banks and thrift institutions and the federally licensed branches and agencies of foreign banks in the United States.
Calling for an end to global conflict at the UNA Global Engagement Summit 2018
Living in New York, just a few miles from the United Nations building, brings global issues into sharp focus. I am a member of the United Nations Association USA, and was honored to attend the 2017 UN Humanitarian Awards Gala Dinner honoring recipients Vice President Joe Biden and Elsevier Chairman and Humanitarian Mr. Youngsuk Chi. Now I have been invited to attend the Worldview Institute Spring 2018 semester.
The Worldview Institute provides a forum in which New York professionals in different fields can engage and discuss global issues with experts in foreign policy and international affairs. The program consists of ten seminar modules geared to develop and enhance the scope of the work and activities of business executives at U.S. based multi-national corporations, as well as professionals within the NGO, UN, media, law, government, diplomatic, and academic communities.
Seminar topics are designed to stimulate informal but academic discussions with presenters from the international arena, and to illuminate and explore business, political, economic, and social trends in different regions of the world. Where appropriate, they also address the role of the UN within these contexts.
The Worldview discussions are led by distinguished lecturers, including UN ambassadors, noted academics, and leaders in global business. For example, Ambassador Riyad H. Mansour, from the Permanent Observer Mission of the State of Palestine to the UN, is opening this season’s semester with an overview of the current situation on the Palestinian home front. Other topics featured in Worldview Spring 2018 include:
Is China Reshaping the World?
Understanding North Korean Political Strategy
Post Brexit : UK and International Relations
The Fourth Industrial Revolution: What it Means and How We Will Live and Work
I am very excited about the opportunity to participate in this seminar series. This knowledge has extensive applications, as world-leading corporations such as BNP Paribas and Coca-Cola align with UN-defined Sustainable Development Goals as part of their Corporate Responsibility Strategy. Launched in September 2015 by the UN, the Sustainable Development Goals aim to end poverty by 2030 while protecting our planet’s environment. It’s wonderful to see corporations in the private sector taking an active part in implementing the SDGs.
I recently toured one of the newest high rises that’s taking shape along the Hudson River in the West Village of New York City. 160 Leroy Street has a unique curvy design by Swiss architecture firm Herzog & de Meuron, making this star the most glamorous on the block. I wrote an article about the West Village’s new neighbor for the WestView News.
As neighbors go, 160 Leroy is more like Sophia Loren than Ralph Kramden, with the two private-elevatored penthouses selling this year for $51 million (7,750 square feet, with a rooftop pool) and $31.5 million (4,849 square feet, with a rooftop oasis), and a modest 9th floor one-bedroom (1,096 square feet, with double exposures) listed at $3.2 million. I concluded that this neighbor is going to be viewed 100 years from now as one of the most exciting architectural examples of our era.
Tom and his wife, Carolyn, having fun at a party in Fairfield, Connecticut during rehearsals for Ain’t Broadway Grand, which opened on Broadway in 1993. Photo by Merwin Goldsmith.
I was honored to write a tribute to Thomas Meehan for the WestView News. He is the only librettist who had three Tony Award-winning musicals run for over 2,000 performances each on Broadway: Annie, The Producers, and Hairspray. He was so highly regarded that the marquees of Broadway theaters were dimmed for one minute in Tom’s memory on August 30th at 7:45 p.m.
The WestView News is published by and for the residents of the West Village of Manhattan; it is a monthly paper with a circulation of 20,000. This is my first piece in a New York publication, and I am thrilled to add this to my list of publication credits, and to be able to celebrate Tom’s life with his family, friends, and neighbors. He will be missed and remembered with love and admiration.
I worked a part-time job at Krystyna’s Place on Cornelia St. in New York this summer. I wanted to connect with people on the streets of New York, as a way of solidifying my transition from Vancouver to New York. I opened and closed the store, served customers, dressed the windows, and created an online store for Krystyna’s Place on Etsy. This web content development project entailed creating all the visual and design elements for the store, including a logo and header. I photographed 30 pieces that Krystyna had selected, measured them, wrote descriptions, and fell in love with the clothes!
This was the ideal summer job, allowing me to bring together my technical writing, photography, and design skills into a practical, hands-on situation with New York people and fashion. Now I can add fashion to the list of industries I’ve written for. For a fuller account, see my Wild Visions site.
I fell in love with New York City (NYC) on my first visit in October, 2014, and moved here from Vancouver in 2017. I petitioned for immigration to the US on my own behalf (without a sponsor or employer), on the basis of being an Alien of Extraordinary Ability (I love that title!) in my field of work, technical writing. The photo above shows my initial application, which was 450 pages long and weighed 8 pounds. Note the patriotic red-white-and-blue color scheme.
I made the decision to immigrate in March 2016, and submitted my application on July 4 of 2016. My application was approved in late December. Super fast! Being accepted for immigration to the United States is a wonderful privilege, and many people helped me by writing letters on my behalf for the application. Thank you all!
“You must be able to demonstrate extraordinary ability in the sciences, arts, education, business, or athletics through sustained national or international acclaim. Your achievements must be recognized in your field through extensive documentation. No offer of employment is required.
“You must meet 3 of 10 criteria, or provide evidence of a one-time achievement (i.e., Pulitzer, Oscar, Olympic Medal).”
I was able to provide documentation that showed I met not 3 but 8 of the 10 criteria, both in the first submission and in this second submission that provided additional evidence (350 pages, 5 pounds):
This was a rare opportunity to turn my technical writing skills to the task of preparing an immigration petition on my own behalf, and I was accepted as a permanent US resident on this basis. This means the US government considers my technical writing accomplishments to be equivalent to winning an Oscar or an Olympic medal. If you need a rock star technical writer to perform extraordinary technical writing and editing for you, you know who to call!
And if you need assistance preparing your own Alien of Extraordinary Ability application, I can certainly help you with that.
So cute words, fun graphics, and pleasing haptics are useless unless there is a solid design foundation and clean, clear language.
