Since last November, everyone has been talking about ChatGPT and thinking about what tasks AI can do for us while we can still keep our jobs. When the same question comes to social media, how can AI help with social media? ... View more

Microlearning is a new way of learning that focuses on reading the exact information you need, when you need it. It's about getting straight to the point and not wasting time. ... View more

"I am tired of hearing that my documentation is hard to understand!”   What if you could make professional looking graphics using no-sweat tools, to take the pain out of consuming software documentation?   I used to be terrified whenever I needed to create a graphic to simplify complex information.   I already knew that the customer didn’t want to read the software documentation. Imagine the hassle of purchasing, installing, and setting up the software. And just when the customer beings to use the product, they hit the pain of reading the user manual.   Providing the necessary instructions at the point when they are needed is at the heart of technical writing work. But how do we deliver it if nobody wants to read it? Doesn’t this drive you nuts too?   There is a constant balancing act that technical writers undertake to write all the possible details for using a product while trying not to overwhelm readers with mountains of text. Then they face criticism because the exact use-case isn’t covered, or because the documentation is difficult to consume and understand.   What can you do as a technical writer? Usually, we end up reworking the documentation over and over in search of that elusive “golden document” that provides our users with exactly what they need.   But the document is still the same pile of words that the user needs to read. And every time you rewrite it, chances are that you add even more words! Let’s be honest here, how many times you have deleted pages from your documentation, when you were asked to make it “simple and easy to use”?   Did the complexity decrease? How about the volume of the documentation - did it grow up or down?   And you start searching for the answers. You sign up and pay for technical writing courses. You start asking questions online. You seek advice and talk (complain) to colleagues. You change the documentation architecture, and undertake customer interviews to figure out how to make it SIMPLER to use...   In the end as a technical writer, what can you do?!   BURN OUT!   Constantly reworking your documentation is an exercise in futility. Do you need to change the order of the documents? Do you need to invest in SEO? Do you need to write a ton of new documents? Do you need to start from scratch?   None of these tactics make much sense unless you tackle the root cause of the problem. What is this root cause? It’s the simple truth that people don’t read!   CUSTOMERS DO NOT WANT TO READ THE DOCUMENTATION!   Why?   One of the greatest inventions of humanity, was the discovery of writing. Written words that can be put on stone, on paper, or on the computer screen, to be understood by other people.   But is that easy?   We spend years at school to learn to read and write. It is not a NATURAL skill that you are born with. It is something that we learn at school.   How do we learn to read? May I ask you to search and find a book for kids that teaches them how to read? What do you see in there?     Z is for Zebra!   Take a look again as a technical communicator! Now think - there is a Zebra image next to the Z letter. An image! Next to the letter!   Why is that? What makes the image so important?   It’s because, unlike reading, human beings are wired to understand visuals in a matter of milliseconds. Not minutes, not seconds, but a fraction of a second! As if our lives depended on it. In the early days, our lives as humans depended on visuals and our ability to understand visual messages from the world around us.   Let’s test your own perception: which one triggers a reaction in you:   The word: stop.   Or…   Which one triggered the biggest reaction in your brain - when you read the word stop or when you saw the big STOP sign?   It’s the sign, of course!   Images activate your brain. You can understand what you see in a fraction of the second. It’s a natural skill that you were born with.   Not like reading! Reading requires conscious effort, then analysis of what you’ve read and then understanding what you’ve read.   Do you think it is different with software documentation? Which one is easier to grasp, a 2-page long text description of the architecture of your software, or the graphic that shows the different components and how they are related?   Obviously, as a technical writer your first reaction will be: “I need to write this down!”. But if you really strive for simplicity, for made-easy-to-consume information, it is a graphic that you should be working on right now.   Simplicity in software documentation means you need to make the information visual, making it easy to consume for your reader.   Not for your manager, not for the development team you work in, not for the information architect of your project, but for the end-user who needs to understand and figure out how to use your product.   Do you agree with this? Have you replaced text with multimedia before? How did it go? Let us know in the comments. ... View more

How often have you fought bitter battles over the names of buttons, actions, or processes? Do you remember capitulating to terrible names just because your seniors demanded it? As technical writers we are naturally sensitive to words, but others rarely share the same feelings.   Names Hold Power Words evoke feelings and associations in the reader and hold the ability to confuse or enlighten in equal measure. A solid terminology base holds a project together, creating a shared understanding not only between customers and developers, but also between development teams. I can recall more than one meeting where parties argued, not because they had different points of view, but because of terminology confusion.   Get Buy In You need your project leads to act as champions for the terminology. They should use the terminology in emails, draft plans, and any written or verbal content. Most project leads understand the need for this consistency; it really does save pain later in the project. Especially with larger projects get the projects leads together to get their group buy in on terms and definitions.   This type of meeting can also help to solidify your “expert status” and assists in cementing a communal understanding between larger teams. Having experienced this first hand on many occasions I can say these meetings can be “fiery” but well worth it in the end and very positive experiences for all involved.   Define Early Strive to define precise project terminology early in the development cycle. If you wait too long, older, defunct terms can become ingrained in your project members memory and surface later to confuse customers and ticket-solvers alike. Define not only your terms, but also the synonyms that you aren’t using to eliminate confusion.   The Right Tool for the Job Finding the correct term for an object or process can be challenging. Between scientific, industrial, academic, and other terminology types it can be hard to find the perfect term. Start out with accepted terminology for your industry, then look to experts in your field, and lastly consider the context and reader: a text intended for use by someone in emergencies should be short and readily identifiable, while one intended for complex accounting process might sacrifice utility for precision.   Your Turn! Do you prioritize terminology for your projects? Do you struggle with buy in? Have you got any great tips to share with the community? ... View more

Software user interface text (any text that displays in the user interface) can help onboard users, build trust, and help users quickly complete their tasks. ... View more

Let’s talk about some of the hidden skills that technical communicators rarely discuss. ... View more

Robot taking over the world With all the hype about AI and robots taking over every job on Earth, I started wondering if my job as a UA Developer was in jeopardy. You can't entirely avoid some human touch when creating help for software products. Can you? I don't think so. You need human intelligence, common sense, logic, and someone to validate the accuracy of your content.  ... View more

We live in a world where people thirst for instant access to the information. This, combined with an overload of information and so many choices to make, if we fail to provide the right content at the right time, users will simply abandon the process and move on. ... View more

If you are a technical writer or an information architect, trying to understand the topic types used in DITA XML, then this blog post is for you.   ... View more

Good technical writing is more difficult than most people think. You can’t simply slap a bunch of facts down on a page and say, “job done”. There’s a craft to writing, a skill you hone over years, and you need to keep practicing and taking in feedback to truly master the pen and keyboard. We learn over time to avoid certain constructions, to follow certain guidelines, to create an appropriate tone, and to tailor our content to our audience. One of the best ways to learn, is to work with a good editor or to edit another writer’s work.   Be the editor you’d want to work with I confess, by nature I’m terrible at giving constructive feedback when editing, especially in long documents. Rather than making helpful suggestions, my gut instinct is to rip into sentences like they were weeds in a garden, shovel phrases around like dirt, and ruthlessly burn terminology I don’t agree with. These are my natural instincts, but they don’t help the writers I work with to expand their skills.   I’ve learned to quash these destructive instincts and to take a teaching approach to my feedback. I’ve also learned that each writer I work with has their own unique turn of phrase that I can learn from to make myself a better author. In my early days as a writer, I remember working with a great editor who took the time to sit me down and talk about things like passive helper verbs and comma splices. This editor is the one I hold up as a great example to others (thanks for making me a better writer Jesse!).   A few years ago, at a group editing session, I looked on in horror as a pair of professional editors destroyed a writer’s work, tearing it apart piece by piece, replacing it all with their own text. A good editor would have given suggestions for improvement, worked in praise and encouragement, and left the writer with ideas they could have taken away. Instead, the writer left with a page of replaced text, no lessons learned, and a dread of future editing sessions.   To be a better writer, be a better reader Our job as editors isn’t to “weed the document garden”, but rather to nurture our fellow gardener’s skills. Each document we read or edit gives us the opportunity to learn and grow as writers. People can surprise you: one of the best technical writers I’ve come across was a developer working in their third language. I learned quite a bit about simplicity and clarity from reading their “raw” documents.   If you want to be a better writer, take the time to read the work of others and learn from their experience. Don’t forget that there is more than just style to consider; by working with another writer, you can learn more about your own company writing guidelines. More than once I’ve learned about a particular internal rule or standard from reading a document where it was used.   Over to you What do you think? What kind of editor are you? Do you work with other authors to help develop writing skills? Do you take part in group editing sessions?  Let us know in the comments below! ... View more