Audience, Market, Product Webinar

As I get caught up on overdue blog topics, I want to thank (albeit belatedly) the participants of my webinar, last December. Unfortunately, I was very sick on the day of the event (so being remote was probably best for everyone), but I want to thank them for their patience. The feedback they provided after the course will help me refine the presentation.

In the mean time, a recording of the webinar is available from the STC at:


Catching up

New WordPress update, new WordPress theme, and look…a new blog post!

Shortly after the last post, my wife and I began the process of moving from the Pacific Northwest to Middle Georgia so I could start working as an Assistant Professor of Technical Communication in the Mercer University School of Engineering. I’m now halfway into my second semester and having a great time.

Lots of things going on and lots to catch up. For now, I’m just blowing the dust off the blog to get back into a more frequent posting rhythm.



Long or short (posts)?

As one of my blog goals, I limited each post to no more than 500 words. My intention was to make them easy to read and write. They seemed like reasonable goals at the time. Since then, however, I’ve read some posts that suggest this might be counter productive. Some of the advantages of long form posts I gleaned from what I read (cited below) include:

  • Long form posts rank higher in search results
  • Long form posts are shared more often
  • Long form posts are seen as more professional

Continue reading “Long or short (posts)?”

Giving criticism

It’s both easier and harder than you think, but here a few points to make it constructive.

Wait ’til your asked

Sure, you can always offer unsolicited feedback, but by waiting until you’re asked gives you the advantage of knowing what they want and that they are ready to receive it. Someone who hasn’t asked for feedback is probably not ready to hear it.

If, for some reason, you feel compelled to offer unsolicited feedback, make sure that you’re doing it for their benefit and not yours.

Understand the context

Even if you’ve been asked, understand whether someone is asking for feedback or affirmation. I tend to ask this directly, which comes of as abrupt–especially when many people don’t know for sure. A smoother way is to gains some context by asking more about the project to understand their motivations for asking.

Providing a critique when someone is seeking affirmation stings, no matter how kind and constructively you are. At the same time, an affirmation seems shallow when someone is seeking constructive criticism.

Know the goal

“What do you think?” is a common way to ask for feedback. If someone asks you this, ask them to be more specific. To give effective feedback, it helps to know how they plan to use it and how much they can change as a result. The best feedback is something that can be applied.

Be constructive and specific

If you see something that you think could be improved, be specific. It takes more time to consider and articulate, but is much more informative than vague observations and opinions.

Cite your sources

If your feedback is based on research, such as recent customer feedback, survey data, or some other research, cite it! Maybe you read or learned something the presenter hasn’t (or vice versa!).

Feelings come from you

Sometimes, you’ll see something that you can’t articulate. There are two options to take, in that case.

  1. You can wait until you figure it out.
    Sometimes it just takes time to bring your thoughts and feelings together into a coherent sentence. In that case, wait.
  2. Other times expressing how you feel is the whole point of the exercise, but speak for yourself. Unless you’ve surveyed the audience, don’t speak for them. “This makes me feel good.” or “I like how you’ve combined the text with the image.” are perfectly fine. “It looks annoying.” really means that you find it annoying, which might bear pursuing, but it is framed in the sense of “everyone will find it annoying,” which is not the case (unless, you have some research on the subject, in which case, see the previous point on sources).

If done right, providing feedback and criticism can be a win-win interaction.

Asking for criticism

Today’s Twitter gem was a Medium post from Mike Monteiro about the place for politeness in criticism–basically saying that politeness has to place in a design critique. Perhaps, but I think respect certainly has a place.

I agree with his premise that it’s “Better to get your nose bloodied in a critique of your peers, than to be slaughtered in a client’s conference room.” I disagree that a bloody nose is necessary “in a critique of [by] your peers.”

I’ll admit that I’ve delivered some of the aforementioned bloody noses–a practice that I’m working hard to reform. And, I’ve received a few, as well. In every case, the bloody nose experience wasn’t necessary, wasn’t constructive, and, in variably, was the result of just doing it wrong.

If it hurts, you’re doing it wrong, or you’re doing the wrong thing (or, you’re just out of shape).

So, how do you get constructive and effective criticism? He mentions some steps in his article that I think they bear repeating.

Get it early and get it often

Waiting until the last minute to get criticism is almost always asking for trouble. First, it’s unlikely that the designer will have time to apply any of the suggestions, so they will just be frustrating at best, and demoralizing at worst. A waste of everyone’s time, in any event, and contributing to the embarrassing experience in front of the client that he describes in the article.

It’s more constructive and effective to get frequent, small-scale, actionable feedback throughout the process, than to wait. This is not an “either or” choice, but a continuum. Nevertheless, lean towards the more frequent end of the spectrum, whenever you can.

Yes, we’re busy, but what goes around, comes around, and we’re all in this together.

Know (and state) the design scope and goal

The goal of the design might not be obvious. Likewise the scope of your involvement (and span of control) might not be obvious. To keep the criticism focused, keep the goals and scope of the design project visible.

Start by saying, for example, “I’d like you to review my redesign of the [xyz] home page to make it more accessible to an older audience. The changes include making the type easier to read, the call to action more visible, and to clarify the client’s value proposition. I’d like you to help me find aspects of the design that could be improved to meet those goals, better.”

In that, you’ve taken 60 seconds to focus the review.

The quality of answers is proportional to the quality of the questions.

If you find that you’re not getting the feedback you want, maybe you didn’t ask for the feedback you wanted. Don’t assume that everyone reviewing your work will know the goals of your design.

Thank them

A friend told me that “Feedback is a gift.” So, like anytime you receive a gift from someone, thank them!

Next up, how to give a helpful and respectful critique.

Time to get writing…

WritingWithQuillI suppose that’s true most of the time. However, last week, I received acceptance notices from the SIGDOC 2016 and the IEEE PROCOMM 2016 conferences for my paper proposals.

These are two of my favorite conferences. They’re big enough to attract a diverse collection of speakers and topics, while not so big that you can’t meet and talk with everyone.

Their venues are also interesting: SIGDOC will be just outside of Washington D.C., so I’m going to have to hop on the Metro and visit the sights.  PROCOMM 2016 will be in Austin, TX. That’ll be a first for me. I’ve been to many towns in Texas, over the years, but not Austin.
Continue reading “Time to get writing…”

Agile documentation in my email

Just shortly after writing a few posts about Agile documentation, I received an invitation to this seminar in Atlanta…

Applying Agile Project Management to Information Development

I don’t know if they have some search-engine magic going on (like Amazon) or (more reasonably) it was just a coincidence in that they were announcing their seminar a couple of months before the event.

It’s great to see that Agile project management is getting some attention in the documentation realm. At the same time, it’s important to understand that Agile isn’t something you can just bring back from a seminar or learn from a blog post.

When I first jumped into an Agile development shop as a tech writer with a solid background in plan-driven project management (a.k.a. Waterfall), I talked to a few Agile coaches and consultants. They all said a 5-year time frame was a reasonable expectation to move from a plan-driven to change-driven methodology. It might happen more quickly, or it might never happen, no matter how hard you try, because requires changing how many people not only view projects, but, literally, think about the world. That was 5 years of constant coaching and encouragement, by the way.

But, in any case, it’s good to see it’s getting some attention. You can’t get to the end of a 5-year transition if you never start.

Agile documentation in the blogosphere

This is a tough topic to research. Using the words “agile” and “documentation” in the same search query returns a mixed bag of results. Some citing that the Agile Manifesto‘s goal of “Working software over comprehensive documentation” to mean that Agile products need little to no documentation. A more realistic and practical interpretation of that line is to treat documentation as any other component of the project.

A project or product should not have features that do not add value. It should not have code that doesn’t add value. Nor should it have documentation that doesn’t add value.

I’ll go along with that, but when it comes to reading what others have to say about technical writing, searching for “agile technical writing” returned this collection (in no particular order):

That’s quite a list and a range of perspectives. They range in age from 2 to 12 years old, with an average of 6.3 years.

Some early observations:

  • The earlier ones seemed to explain Agile more than the more recent articles.
  • They all offered tips for writers in one form or another
  • About half were written as first-person experience reports and the other half in more of a third-person, instructional format.
  • Most were written in a narrative format with a few as just bullets or bullets with some details.
  • Only a few cited additional references (although most had embedded links to related topics)

I’m not sure what conclusions to draw from this, yet. For perspective, I wanted to do a similar survey of academic literature, but searching for “Agile technical writing” didn’t produce much to read. Hmmmm….

Agile documentation in the real world

In Agile documentation in practice I described what worked for me, which works, when it works, but it’s not without its challenges. However, if you can get these right, the process should be smoother.


First and foremost, it works best when everyone is on the same page. When stakeholders have different ideas of quality, content, scheduling, iterations, or priority, things become difficult. This should come as no surprise, but it’s worth repeating because without a common understanding of the ground rules by all the stakeholders, those disagreements complicate all of the other areas.


In Agile documentation in practice, I mentioned how the traditional writing process was not what worked for me in an Agile shop. When I matched my writing process to the coding process as much as possible, things became easier. Once I was able to plan and describe my process in terms that made sense to agile software developers—something that I couldn’t do until I embraced the process for myself—it was easier for them to understand what I was doing (and when I was doing it).  Reporting progress clearly and frequently is an essential part of a successful process (Agile or otherwise).


A big part of the process consists of the tools used to execute the process. Agile is designed for changes. Changes in requirements. Changes in features (content, for documentation). Changes in audience. To name a few. The tools used to manage the workload and the content must accommodate the changes you want to accommodate as easily as possible.

Which tools are best? That depends on your process (and is worthy of a topic or two in itself). Ideally, the process will define the tools, not the other way around. In reality, however, this is often difficult to apply in practice. At least, with a clear process, you’ll know what your tools will need to do.


Collecting and analyzing data must be integral to the process. Data such as audience requirements, product road map, market climate, at the high-level and direct customer feedback, usage and satisfaction metrics, and production metrics at the detailed end, to name a few. Without a constant calibration, the writing process becomes increasingly disconnected from reality—and remember, reality is a moving target, which is why you need to keep your data up-to-date.


If you’re an Agile shop, this shouldn’t be a problem you can’t handle because the sprint planning process takes this into account. Each sprint has its velocity (capacity) for development tasks and it will also have its velocity for technical writing. This always begs the question:

What is the right ratio of developers to writers?

It depends, of course. But if you have all of the above, you might not have enough writers to produce everything you want to deliver, but you’ll have the process to do the best you can with what you have and the data to know if you need more or fewer.