There is a breed of writers who can write a whole book in one sitting. They write and write and in two days they produce a whole novel. According to Wikipedia, Stephen King is famous for doing just that. Great, isn’t it? But it’s not like that in technical writing... ... View more

It feels like the only thing that we're talking about in the tech world recently are Large Language Models or Generative AI. It’s created many conversations, both positive and negative. In this Blog, I’d like to look a bit deeper at how LLMs work and what they can do (including the effort to achieve this) and what they can’t.  ... View more

Design Thinking is about problem-solving and collaboration between a team of people with different skillsets to come up with innovative solutions for users. This process is typically for creating software solutions, but I learned how to adapt it to create user assistance solutions for our users.  ... 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

Have you ever played the falling tower game, Jenga? In this game, you build short wooden blocks into a high and stable tower. Once ready, each player takes a turn to remove the blocks until the tower’s structure becomes unstable and it collapses with lots of noise and laughter. It’s always fun, but you should avoid playing this game in the evening – the neighbors rarely appreciate the noise!   Don’t you also get upset when writers play Jenga with documentation? In technical writing, content should be logically organized and properly structured. Why? Because you need to provide a single topic as an answer to a single question. It can be surprisingly difficult to come up with only one answer and write only one topic to serve that purpose. It’s always tempting to write content in a more generic way and put all the information in a single topic. After all, this requires no effort! Just writing what you think the answer should be and putting all the variations of the answer in the topic is so much easier than breaking it down and analyzing the different variants of this answer.   Don’t be tempted by this approach! Your readers want the answer to their question, not a slew of answers where the one they need is buried with a dozen others or hidden under several levels of nested content. The art of writing technical documentation includes building the holistic structure of your documentation topics by topic, answering one single question at a time, and leading the customer to the goal of your documentation – which is to solve their problem. Let’s look at an example.   How do I paint a house? It is a rather generic question. You cannot write one single answer to this question, because you need to know the context around it. How big is the house? Are there angles to be painted? What is the condition of the walls? Are there preparations to be made. You see, when the answer is that generic, you need to lead the reader through a sequence of related topics. Each topic answering one-by-one the reader’s questions, leading them to the success of their project. Your documentation should try to follow the sequence of activities to be undertaken, regardless of the starting point. XML templates - such as those offered by DITA - can assist in structuring your writing. Using DITA you can create Concept, Task, or Reference documents, with predefined elements, facilitating you in capturing the structure of your documents. Make sure to give a proper structure to your documentation and never mix the content of the topics to mix the content of several answers! Keep the content of each topic straightforward and clear for the reader. Build it one brick at a time to create stable documentation that really helps!   Now over to you! What do you think? Do you have rules for how you structure your documentation? Do you have ideas for different approaches or more dynamic approaches? Let us know in the comments!   ... View more

Do you think user assistance and product documentation in particular have a fashion sense? Or technically speaking, do they have a style? Do you think they have the right style? Do you need a guide for styles? Who comes up with such a style guide? Will a style guide make a difference to writers? ... View more

Enablement comes in many forms. Trying to succeed and move forward in your career? You’ll probably take a course to earn a badge or certification to prove you’ve got the skills to work in a new role or with a new system. This is what we typically call “learning”. But even with training completed, you could need support and require enablement materials while performing hands-on tasks. This is referred to this as help or documentation. Both types of enablement are equally important and are often intertwined. But is there a difference to consider when creating help or learning materials? ... View more

Do your readers complain about not being able to find what they need to get their job done? Even though the content is right there in the manual? Here are a few ideas for helping your readers locate what they need within your documentation structures:   Try it Yourself Becomes the “first customer” by running through the software/process you are describing yourself. It’s amazing how many potential issues you can find and questions you’ll locate. This will help place you in the mind of the reader and know where you should put content in your documentation structure, so it appears in the right place.   Use Parallel Terminology Customers usually start searching for help using the same terminology and process flow as appears on the user interface. Try to make sure that you use the same flow and terminology so that when your customer starts searching, they’ll immediately draw parallels and feel comfortable.   Progressive Disclosure Don’t flood the reader with too much data early on. Slice up content so that it’s task-focused and slowly expands on more detailed ideas and processes. Try to stifle the urge to give all the information to the customer at once.   Look for the High-Level Use Cases Is there a natural split in the use-cases for your documentation? Maybe you have some documents for setting up the software and others for daily operation of the software. These are likely to have different readers, and so, not only could you place them in different high-level structures you can also pitch the tone of the documents differently. For example, you might have a “working with X” structure and a “configuring X” structure. The former would target day to day users while the latter might have a more technical tone and target consultants.   Give your readers a map! Paper manuals usually have tables of contents, but the nature of online documentation means that the structure itself often replaces a table of contents. Still, it doesn’t hurt to include a document or interactive graphic that points your customer to the right place.   Use Multimedia Multimedia can be a powerful tool for overviews and orientation to a topic. The combination of screen captures, animation, and voice really helps improve general understanding. It’s also a great way to introduce written documents and point the way to further detailed reading.   Over to You What do you think? Did we miss something? Do you have a great tip for helping your readers find what they’re looking for? Let us know in the comments below; we’d love to hear from you! ... View more

Have you ever searched for an answer on the web, finally found what seemed like useful data, then realized the date stamp was from 5 years ago? I have, many times, and this is an experience I'd like to avoid for any software user trying to find help either in-app or in an online library. That's why I believe that maintenance of enablement content is as important as creation of this content. ... View more

 You can apply some simple psychology principles to your UI design to predict and explain customer behavior. Thinking, feeling, and visual perception are important to make sure your users have an enjoyable (or less frustrating) experience and return to your site. ... View more