Since much of technical writers do is gather information from other people, be respectful of their time. Don’t ask for a minute unless you literally want 60 seconds of their time or less. If I have what I think is a brief question requiring a brief answer, I ask, “Hey Dan, do you have a few minutes to answer a question, or should I come back later?” They’ll usually be honest about whether they need to finish something first or if they can give me their full attention right then.
Looking back over recent months, by far the most common form of research I’ve carried out is that stalwart of qualitative studies—the interview. A simple, semi-structured, one-on-one interview can provide a very rich source of insights. Interviews work very well for gaining insights from both internal and external stakeholders, as well as from actual users of a system under consideration. Though, in this column, I’ll focus on stakeholder interviews rather than user interviews.
Some years ago, I used to suffer from developer neglect, or to use a more scientific term, from a kind of information exclusion complex. You know what I’m talking about. Developers make updates to the interface, often at the last minute, and don’t let the tech writer know what changed. As a result, the help is wrong and out of date. It’s a frustrating experience from the writer’s perspective.
Technical communicators frequently collaborate in workplace projects and bring a host of different kinds of expertise to this collaboration. Yet the understanding of communicators’ expertise among managers and subject matter experts is grounded in a view of writing as a finished product and authorship as singular. This article documents many different kinds of 'contributory expertise' employed by writers collaborating to produce articles for publication. Expertise in research, textual composition, visual composition, as well as other kinds of expertise garnered on previous projects is often brought to collaborative projects. Often emerging and developing as a function of collaborative work is expertise in framing the project, conducting review processes, and assessing outcomes. These categories are discussed in some detail to provide practicing communicators with ideas for documenting expertise in their specific workplaces, to provide students with ideas for developing expertise in various areas, and to prov
Efficient, effective collaboration between UX designers and stakeholders is an essential ingredient of a successful project. Stakeholders bring their unique perspectives to a project, and their feedback can help a designer understand the design problem space and develop solutions that align with business and technology objectives. But simply asking stakeholders for feedback can lead to misaligned expectations and communication problems. By being thoughtful in how you make your request for feedback and by providing simple questions and instructions, you can ensure that you identify potential risks early in the design process, minimize stress, meet your deadlines, and ultimately design a better solution.
If you have ever worked with a developer or a development team, this article will probably strike close to home. As designers, we work with dozens of developers across the globe each year. Some of us are fortunate enough to find a gem; a developer that just gets it. A developer that you feel is on your same wavelength in terms of what needs to be accomplished with the user interface, and what it needs to happen. Most often, however, we find developers that we generally don’t see eye to eye with.
Send the mail to the person or group of people, but rather than asking the question, state what you know is the wrong answer. “I think the way it works is Foo, right Bob?” You'll be amazed at how quickly someone will take the time to correct you, particularly if the question was aimed at more than one person, since it's an opportunity for that person to prove their knowledge in front of others (which is just human nature).
Improving technical reviews, when subject matter experts, or SMEs, review content for technical accuracy, is a challenge every technical communicator faces sometime during their career. Every year, journal articles are published, presentations are made, and discussions are initiated on this very topic. Most of them conclude that SMEs are difficult. It's your job to bribe, cajole, or coerce a better review out of your SME. I don't agree.
An SME is someone who has been trained and has worked in the area that is being targeted for the new application. At Autodesk, we have found that pairing SMEs with Interaction Designers is the most efficient and successful way of meeting user centered design goals.
A little introspection and a rewind of sequences from my years of experience as a technical writer, revealed a patterned behavior in most developers. The basic fact that some developers have no idea about what inputs to give and what to expect of a user document is the primary cause of such inputs.
A 20 minute monologue about the best way to get information from SMEs--sit by them, permanently if possible. Many IT organizations station the writer remotely from the developers, programmers, and other SMEs, but nothing could be more damaging to getting the information you need. Increasing your proximity also increases the communication you receive.
A 20 minute monologue about the best way to get information from SMEs: sit by them, permanently if possible. Many IT organizations station the writer remotely from the developers, programmers, and other SMEs, but nothing could be more damaging to getting the information you need. Increasing your proximity also increases the communication you receive.
Just the thought of dealing with Subject Matter Experts (SMEs) can create stress in the life of any documentation manager. Some SMEs can be self consumed, preoccupied, distant, and even rude. But why do these behaviors exist? This article briefly describes how to interact with people who might be difficult to motivate and how to work with people who have priorities different from yours.
Part 2 switches the focus to members of your management team and what you can do to sell your team’s professionalism. Also included are hints on how your writers can individually sell themselves to gain cooperation from SMEs.
The development of a modern software product is a complex process involving a variety of disciplines, including that of the technical writer. It is essential that the writers establish close relationships with all other groups in the process and that they build effective and efficient systems of communication between them. The job of the writing manager is to ensure that the writing team obtains the information it needs in a timely manner and that the group interacts effectively with other groups in the process. This can be achieved by a blend of intergroup communication, background research, documentation and schedule planning and a well organized documentation review process.
If developers only hears about bugs, problems, quirks, errors, and other issues, where’s the motivation to code? In a recent post on Joel on Software, Joel Spolsky stresses the importance of giving positive feedback to developers, not just negative. But there was no where to log my praise in our bug tracking system.
What should technical writers ask engineers when writing support materials for a product’s end users? Guest blogger and leading tech comms expert David Farbey wraps up his ‘What to ask…’ series with questions for engineers.
Double agents on writing teams provide benefits to both product developers and technical writers with their unique skills and perspectives. You'll be more likely to get the information you need when you need it because your double agent has already set the stage for success. Learn the benefits of having a double agent working with technical writers as a part of the product development team. Discover valuable secrets never before divulged to the public that you can use to work with your product developers. Take out your magnifying glass and look for the clues.
I admit that I don't know everything about subject-matter experts or SMEs (rhymes with please). But I do know that there are some things that you should avoid asking SMEs, the main ones being 'Does the user know this already?' and 'Do I need to explain this to the user?' The problem with these questions is that the SME is likely to reply 'No!' to both of them when in fact the answer is most definitely 'Yes.' SMEs tend to believe that everyone knows as much about technology as they do. Never, never, never let the SMEs tell you how to write the documentation. A SME is the subject matter expert, not the documentation expert (that's you).
Most companies want to be recognized for producing usable products, for the quality of products must be high if they are to be accepted into today's competitive market. However, usability planning relies on interaction with other departments and their members. In other words, the most successful way to ensure product usability is to set up a test team consisting of representatives from various departments. This paper details the members of that test team and discusses their overall responsibilities in the testing process.
Almost a decade ago, Walkowski's (1991) study of the interaction between subject-matter experts (SMEs) and technical writers focused on the perceptions of software engineers toward technical writers. Her findings gave technical writers insights on how to improve critical relationships with these organizational colleagues. This study partially replicates Walkowski's (1991) study of technical writer-SME interactions, but instead of collecting data from SMEs, we surveyed technical writers themselves. We report perceptions collected from 31 technical writers and contrast them with Walkowski's original findings, offering interpersonal and organizational recommendations for addressing tensions between these groups. By examining both the SMEs' and the technical writers' perceptions of their relationship, we are able to provide a two-sided view of a dynamic and complex interaction. We also argue that participants in the SME-technical writer interaction cannot fully alter their relationship without the strategic supp