Most technical writers have a complicated relationship with feedback. We have the desire to make things better, but it can be difficult when our documents become personal. Each year the STC Competitions provides a way to obtain the feedback we desire in order to become better writers.
This past year I entered an internal DITA resource in the STC Carolina Chapter Competitions. I knew it had its flaws, but I wanted to see if other writers agreed with me and (hopefully) found some things I didn’t. The feedback I got wasn’t what I was expecting, and no one mentioned any real problems.
Many of us simply don’t know how to give constructive criticism that is specific enough to be helpful. Here are some ways to give better documentation feedback.
Critique, Don’t Edit
STC judges are reminded that judging does not mean editing. When providing feedback about a document, focus on the entire document as it’s intended to be used. If you notice writing mistakes, provide that as one item in the feedback (with specific examples of course).
Know the Difference between Praise and Criticism
Many conflate “criticism” with “negative feedback.” You can be positive without resorting to simple praise. Here are some examples:
Praise: The images and text work very well together.
Constructive criticism: I’ve noticed that a few of the images and text don’t work contextually together. (Remember to give examples.)
Praise: The document is usable and easy to read.
Constructive criticism: The document’s usability could be improved in the following ways…
You can be positive while also accentuating the issues. This is the type of feedback writers are looking for.
Note: The “Sandwich Method” is Unnecessary
Being positive when giving criticism doesn’t mean that you have to “soften the blow” with praise. Whenever I get a criticism sandwich–praise, criticism, praise–I just want to roll my eyes. We’re not children; we should be able to handle the criticism on its own.
Give Specific Solutions to Specific Problems
If you see a document that needs more than just a professional edit, call out specific problems and ways to address them. For example:
General: The pages feel a little cramped.
Specific: While the images are contextually appropriate, I feel they could use more surrounding white space. The current space between the text and images makes the page feel more cramped and therefore slightly harder to read.
General: Your font choices are appropriate.
Specific: The heading and body fonts you chose are great for this document because they are large enough to read and provide enough contrast. Nothing is distracting about the words, and it makes reading this document more pleasurable.
**Note: Although many of us have no control over our corporate style, when several people agree that something isn’t working, it’s easier to get those style choices changed. Similarly, disagreements in the author’s group might be helped if their style choices are validated this specifically.
General: The content is not adequate for the intended audience. (Whoa!)
Specific: The document is targeting novice users, but I feel that it needs more introductory material to help orient beginners. For example, the product overview should include more than just features, but what the user can do with those features. Also consider a “Getting Started” chapter to include this information that more advanced users can skip over.
Focus on the Document, not the Person
Feedback is personal, but the author won’t feel attacked if it’s presented the right way. Focus on the document, not the person who wrote it, and remember to be compassionate.
Personal: You need to edit your document.
Not personal: I’ve noticed some typos and a few minor grammar and spelling issues, so I recommend having someone proofread the document before publishing.
Filed under: Uncategorized | 1 Comment
Tags: STC Carolina Chapter
If you’ve ever been on a software project where UI changes that affect your documentation are made frequently, you understand how frustrating writing about it can be. With FrameMaker, variables make this a cinch. In DITA, it’s not so straightforward. But the power of content reuse can save your production time — and your sanity.
Enter the humble conref, or content reference. On the surface, a DITA conref is a simple way to reuse content in multiple places so updating is quick and easy. Using conrefs, DITA elements can become variables.
I recently worked on a software documentation project where the need for variables was clear from the beginning. I decided to create a list of reusable UI controls, windows, and screens, so that when the a window or button name inevitably changes, I only have to update it in one place.
Here’s the overall process I used:
- Create one topic for reusable elements.
- Make a list of all GUI controls.
- Give each element a unique ID.
- Use a conref to the reusable elements in your content.
Create one topic for reuse.
I made one topic to house all the reusable elements. Hint: name the topic so it sorts to the top of the folder structure so it’s easier to find (an underscore or other symbol should accomplish this).
Make a list of all GUI controls.
In the reuse topic, list the names of all buttons, window titles, tabs, pages, and dialog boxes using the elements wintitle and uicontrol. Wizard and dialog box text fields, drop-down menus, and check boxes are recommended as well, though I didn’t go to this level of detail. This will take some time, but is definitely worth the effort.
To help GUI controls with the same name stay away from each other, divide the list into different sections.
Give each element a unique word-based ID.
Each element should have a unique ID that is easy to find and remember. I recommend using words instead of numbers for this reason, especially when you have hundreds of elements. Phrases such as “save-dialog” and “save-button” will keep the guesswork to a minimum, especially when GUI controls use the same name.
Insert a conref to the element.
Finally, in your content topic where you want the variable element to be used, reference the element’s ID. oXygen’s wizard (shown below) makes this quite easy.
You’re done. Enjoy your sanity!
Filed under: DITA, Work | 2 Comments
Tags: DITA, reuse
On November 18th, 2010 I gave a presentation to the ECU English Students titled, “Landing Your First Technical Communication Job: 60 Tips in 60 Minutes.” In the 45-minute talk, I gave tips on how to:
- Find tech writing jobs
- Write resumes that work for hiring managers
- Network locally, globally, and using social media
- Update skills and keep up with technology for free or cheap
The presentation was recorded, but I don’t know if I will get that link yet. But for now, here’s a link to the presentation. Enjoy!
Thank you to all who contributed advice for the students. You can read those comments here.
If you enjoyed the conversation or have more questions, please feel free to comment below.
Filed under: Education | Leave a Comment
Many technical writers play document manager at some point in their career. Part of document management includes managing — and many times, creating — templates for colleagues to (mis)use.
For those of us not using FrameMaker, DITA, or other type of single-sourcing, template creation and maintenance can sometimes be the bane of our existence.
I’ve compiled these ten best practices for creating and managing templates. Some are Microsoft Word(R)-specific, but most you can apply to any software you’re using.
1. Create templates for each major type of document.
You don’t need 20 templates, but you probably need more than just a few. Think about what your company communicates (and how), and start there. The ones you will probably need are:
- Letters, memos, and envelopes
- “Formal” (long) document for proposals, plans, and reports, etc.
- Policies and procedures
- Agendas and meeting minutes
- Forms and logs
- Labels for binders, CDs, and other data storage
- Fax cover sheets
2. Don’t use a template as a style guide.
When I first started creating templates, I made the mistake of using a template as a way to convey the company’s preference on style issues (punctuation, spelling, etc.). I quickly realized it was getting WAY too long for a simple template, so I created the style guide using one of my new document templates.
However, do give your users some helpful hints on the practical (not theoretical) use of styles, tables, references, captions, bullet lists, headers and footers, page breaks, etc.
3. Use styles and give examples of them.
Many people don’t know how to apply styles, much less which ones to choose. Provide example text in the body of the document so the user gets a good idea of what they’ll look like.
Along with that…remove custom styles you don’t need.
In Microsoft Word, there are many default styles that Word graciously provides (forever). If you have custom styles for your template that you’re not longer using, delete them from the list; that way, colleagues are not tempted to use them.
4. Don’t use the .dot extension in Microsoft Word.
Microsoft was trying to do us a favor by creating the template extension. But I’ve found that when you’re creating templates and you continue making edits after it’s saved, you will have to re-save the template under a new name, and delete all previous versions, which is just a headache when you do this multiple times. (If you really need to use the .dot extension, don’t apply it until after the template is as complete as it will be [it will change, though].)
If you’re annoyed with this “feature” as I am, create a read-only version .doc or .docx file, which are easier to edit and save. Template users will be forced to create a new document without all the hassle of a true “template.”
5. Perform a few usability tests.
Allow someone on your team to use the template and provide feedback on problem areas, styles that don’t quite work, and other issues that may pop up.
6. Don’t distribute templates until they’re FINAL FINAL FINAL.
If you let it, the editorial cycle can go on forever. So after you’ve allowed the last round of comments to happen, make sure the template is completely final until you let everyone know it’s free to use. It’s not fun when people are using your templates before they are completely ready.
7. Control the versions.
If you’ve ever had to retro-fit documents into new templates, you will know how painfully time-consuming and frustrating it can be. You will never remember what changes you made from version to version of your templates.
Version control is a very important part of document management, and working with templates is no different. If you edit your templates after they’ve been distributed and are in use, save the new templates with a new version number and date.
In addition…store templates in one location.
Can you imagine if everyone had a soft-copy version of the “official” template on their personal machine? Version control goes right out the window! Store your read-only templates in a file share or other document management software, and allow edit access to only a few key people.
9. Know your history.
In addition to creating separate versions, create a detailed change history for the template, as you would with any other document. Update this section of the document with each new version.
If you provide a sample “change history” or “version control” section of your template, it can act as double-duty for the change history of the template itself. Include little things, even spelling and grammar.
10. Don’t overdo the branding.
There’s nothing more annoying than having a logo on Every. Single. Page. What’s worse is if you have more than one logo repeating itself. Does your audience really need to see all the logos, URLs, and phone numbers everywhere?
Okay, I lied. I have 11 tips, but the last one is very useful if you can manage it.
11. Train your users.
No doubt you will have adept, average, and novice users of the tool you are using to author documents. If you have the luxury of time, give them a tutorial on how to get and use the templates. If your users are not writers (i.e., are not involved in the post-authoring part of publishing corporate documents), I strongly suggest giving them a brief overview of your company’s document life cycle.
What are your tips and tricks for managing documents, especially templates?
Filed under: Work, Writing | Leave a Comment
Has someone ever said something like this to you? Basically what they’re really saying is,
I’m not a technical communicator, but anything I write is 100% perfect and shouldn’t be changed!
Now, I know that even everything that *I* write isn’t perfect, but if someone wanted to change one of my documents, I would want to know if they’re really not working (someone may just have a different style/format/color preference), and also why (a.k.a. user testing, which should always be done, but usually isn’t).
I’ve had to deal with some pretty touchy people in all my jobs. A former boss and I call this reluctance “The Bucket Syndrome” (TBS). Everyone has a bucket of stuff they don’t want to let go of. Usually that bucket is filled with documents and other stuff they created that they think doesn’t need to change. TBS became a daily joke when I found this picture, which we used in our presentations to the rest of the staff to remind them to let go of their buckets.
At my current job I work part-time in a lab where I test samples sent in from our customers and service centers. In the testing kit they pay for, there are some brightly colored instructions so they don’t miss them. Inevitably they perform the test wrong, which makes my life a hassle, but it could also skew the results. I asked the person running the lab why he thinks this happens and he says, “They don’t read the instructions.” And I asked in reply, “What if they do read them but they’re just not understanding something?”
That’s when I got the fiery retort that made me recoil a little bit. Never had I seen someone so protective over a small set of instructions.
So, will I perform user testing and ask the customers what’s wrong? No, it’s not allowed (we’ll see about that). So, I get to write a form letter that tells them to RTFI! I may make a video and put it on our new website, whenever that gets done.
What’s are some “Bucket Syndrome” responses you’ve gotten from customers or co-workers? What did you do?
Filed under: Work, Writing | 1 Comment
I’m putting together a presentation for technical communication students at my alma mater, East Carolina University in Greenville, North Carolina. I already have a bunch of tips on the following topics, but I want to hear your advice!
- Types of work you can do (thinking outside the “software box”).
- Specific tools you should and shouldn’t learn.
- What STC certification means for new graduates.
- Practical ways to find your first tech comm job (including resume tips and local tech writing companies and contract agencies).
- Networking that doesn’t always involve social media (e.g., STC involvement and volunteering).
- Tips for blogging, Facebooking, and Tweeting.
- Portfolio basics.
- Continuing education do’s and don’ts.
What advice would you give? It doesn’t have to fit within the topics listed above. Basically, this is “If I knew then what I know now…” kind of advice. Leave a comment below to submit your advice and tips.*
I’m also new at this (I don’t claim to be an expert), so I imagine your tips will help me as well!
*Note: Obviously I’m asking permission to quote you in my presentation. I’m also going to be showing this blog to the students, so if you don’t want to use your real name that’s fine with me!🙂
Filed under: Education | 6 Comments
This is the first post of a series I am calling Confessions of a Technical Writer, or, if you prefer, The Down and Dirty of Technical Writing. In my limited experience as an official technical writer (titles are just semantics, right?), I have encountered people, company policies, and situations that are too strange — and sometimes too funny — to make up.
I apologize in advance if this series becomes a journal-like stream of consciousness where my meticulousness is evidently lapsing. Also, and I hate to do this, but names and places are changed to protect the guilty. Networking sites just ruin all the fun.
That said, I present:
I wouldn’t have believed that some people really meant it when they say, “It’s my way or the highway.” I was preparing to present at a writers’ meeting, and a glorified secretary (no title that was recognizably important) “organized” it. Imagine me saying that with air quotes. I was at Slow Software Company (SSC) for three months (felt like years to me), and we only had one meeting, mostly because people at SSC couldn’t be bothered enough to care. About anything.
Glorified Secretary of the Minutia asked me to send her my materials so she could make sure I didn’t conflict against our style guide (which I had never seen at this point). I thought this was a reasonable request, but I made the mistake of thinking she could edit a PDF and be clammy-happy. Well, there’s my confession: I didn’t know that there were more controlling people than me.
After I spent meticulous hours editing the darn thing (and yes, reading the newly-acquired style guide), I thought the presentation had good advice without being controversial. After a prompt rejection of my PDF, I sent her the original file, which I received back from her (the day before the meeting I might add) completely blue lined. Apparently, she was traumatized by her red-pen-wielding evil English teachers. Blue everywhere.
So, avoiding confrontation (like I do), I send her a respectful email saying thanks for your opinion but I couldn’t care less. After a few rounds of arguing semantics and details, she finally proclaimed that if I didn’t make her edits — all of them — exactly as she had written them, then I wasn’t allowed to present at the meeting. Wasn’t allowed to present!
Well, obviously you know what happened then. I agreed that I wouldn’t present, Glorified Secretary of the Minutia, thank you very much. But, that would be wishful thinking. I presented anyway, and at the meeting she announced she and I had had “an interesting discussion” about the presentation, but I did a “good job.”
Did I learn something from my sin? Yes: take the Highway when it’s worth it.
I no longer work for the Slow Software Company as I am now with Highway Robbery, Inc. Check back soon for more Confessions!
Filed under: Confessions | 2 Comments
My mentor once said,
You have to be a little weird to love working in this field.
I find this to be a true statement, especially for me. But it also got me thinking about the common interests among professional communicators, some of which may be considered “alternative” to the mainstream (vampires, renaissance fairs, or heavy metal bands).
I never really noticed that several people from my STC Chapter enjoyed renaissance fairs like I do. I have always known _I_ was weird, but seeing it confirmed through other weird people makes me laugh and cry at the same time. Some of you that always go against the grain may say, “Who wants to be normal?” I get that, but I think everyone wants to be normal, at least within their peer groups.
At my last job, someone made a comment to me that I muddled over for a while, and now I open the Pandora’s box to a conversation about the perception of technical writers and other “techie” type people. This person said,
You’re so personable and fun to be around, not like all the other technical writers I’ve worked with.
My response was basically surprise. Because, as I’m sure you can agree, most of the tech writers (or user experience designers, or instructional designers, or editors) are for the most part, fun to be around and people you enjoy working with. I haven’t personally known any extreme introverts, the kind this person was obviously complaining about.
Why do some people consider technical writers nerds? Is it because a lot of us are into “weird” things?
Now it’s your turn…
How do you perceive technical writers (and other communicators). Are you a nerd? What “weird” things do you enjoy that you find other techcomm professionals enjoy as well? Go ahead and share your darkest secrets…I won’t tell.
Filed under: Uncategorized | 1 Comment
At an interview recently I was asked, “How do you build trust?” After thinking about the question for a moment, I answered,
Building trust requires that you be honest and transparent. Also, delivering on your promises instills credibility and helps build trust.
I think that was a pretty good answer for thinking on my feet. Looking back, I realize my answer comes from experience. I, along with many other technical writers, am familiar with:
- Being accused of not being an “expert” or at the very least not understanding the topic/industry.
- Encountering resistance, from little speed bumps of disagreement to mountains of cultural dysfunction.
- Avoiding political games and power plays, or at least staying neutral if caught in the middle.
I mention these three things because learning to work through these obstacles and still delivering on your promises builds trust. After two months at my current position, my supervisor realized I was everything I had promised, and left me to do my job. My responsibilities increased and I began to build trust and credibility among the staff in my department.
Credibility (or ethos) is a very important part of communication and rhetoric. If your audience trusts you, they are more likely to listen and do what you are asking them. In rhetoric classes we learned that ethos comes from things like good use of branding, the author’s personal credibility, and the association with a credible source (such as a university or well-known company).
I think building trust and credibility should be something we are all consciously aware of in any job. My current employer, as a company, is focusing on being transparent with the public to build trust in shareholders and customers. At the employee level, that means:
- Being honest when you don’t know something.
- Owning up to mistakes or sharing the blame.
- Communicating every step of the way.
I have learned these things from making mistakes and calming stormy waters when things are unclear.
How do you build trust among your peers and credibility in your writing?
Filed under: Work, Writing | Leave a Comment