Category Archives: Writing Responses

Doc Plan schman: Teacher response to homework #5

Business Keeping

Grades will always be posted to Canvas. Check for them there.

Doc Plans Are a Must Because Documentation Is a Lot of Messy Work

You may be wondering why technical communicators use doc plans when you have already created several forms of documentation without them. And the answer is: it’s because of complexity. The documentation we’ve created in this class is just a small piece of what technical communicators do out in the world. Some of their documentation is hundreds or even thousands of pages long! I’ve heard of help forums with 10,000 individually-moderated pages. With that much content, you need a plan or you will quickly get lost in the process.

The purpose of these types of documents is to provide a schedule for the deliverables, including their management, development, and creation. Estimating needed human resources and creating timeline are some of the tasks completed at the beginning of a documentation project. It is project managers who complete these documents rather than technical writers. It is way of making needs explicit at the beginning of a project. – Gergana

Project Management Is a Highly Underrated Skill

The further along I get in my career, the more I value project management. I happen to be really good at project managment, but, in my experience, most people are not. And I have worked with plenty of people in the corporate world as well. Most people seem to apply to “putting out fires” approach to project management which involves running around trying to accomplish daily tasks with no discernible plan. This is a great way to get stuck with little responsibility and a lot of menial tasks in an organization. Organizations don’t like to promote people who can’t manage their projects because there will be even more consequences if bigger projects fail!

The definition of project management seems self-explanatory on the surface. It seems like it would just be managing the how and when of a project getting done. It’s actually much more complex because in a professional or business setting, it involves managing all the details of what goes in to completing a project. The article “Project Management and the Technical Communicator” states that project management includes “acquiring and leading the resources (money, materials, staff, facilities) necessary to accomplish the project goal successfully, on time, and on (or below) budget” (Leahy 2018). Communication and organization are probably the most useful project management skills for a technical communicator. Project managers and technical communicators need to be able to communicate with their customers, teammates, and subject matter experts. Organization is a necessary skill for technical writers because their deliverables rely on being organized, concise, and coherent. Any skills gained from project management are easily transferrable to technical communication. – Tamara

Agile Is a Key Workflow to Know About in the Technology Sector

To understand modern tech comm, you also need to understand Agile. Modern projects are not linear, they are iterative, which means they change with each development cycle. Back in the day, before Agile, you could just wait for the product specifications and then create your documentation completely divorced from the development process. Now, if you do that, your documentation will be hopelessly out of date by the time the product launches.

This is why technical communicators are almost always part of cross-fucntional teams now. They need to change and adapt their documentation as product specifications change and adapt during the development cycle so that by the time the product launches, the documentation matches it perfectly.

Agile product development is a collaborative approach to product development in which the scope of work is constantly adjusting to ensure the most important tasks and deliverables are completed first. A project is divided into iterations,which focus on the most important tasks/deliverable from the backlog and once an iteration is completed, the list then updates to what is most important based on work already completed (the list does not change during an iteration, only in between). The agile method allows for adjustments to be made to timelines if necessary,with the backlog updating accordingly to show what deliverable is most importan tbased on these changes. Cross-functional teams will complete multiple iterations of the project before it is completed, until a market-ready product is produced. – Gabriella

Teacher response to module #4

Business Keeping

Grades will always be posted to Canvas. Check for them there. You also receive individualized feedback on modules, so be sure to log in to check your feedback to avoid future grade penalty.

UX Deliverables Are Documentation of Design Processes

The most important takeaway from this module is that the function of UX deliverables as a form of documentation is to orient designers to design processes. Design processes for applications like the ones you reviewed for this module are now exceedingly complex and involve teams of programmers, designers, UXers, marketers, managers, technical communicators, etc., etc., etc. Someone has to document the design process and orient its shape! That person is the UX designer.

UX designers are thus part project manager, part usability specialist, and part technical communicator. They wear a lot of hats, but their primary goal, as I explain below, is to keep users at the center of the process.

UX Deliverables Insert Users into Design Processes

UX stands for “user experience.” Keyword: user. Besides having users sit at the table with you while designing a product (which is a thing, actually: it’s called participatory design), it can be hard to insert them into a design process. What do they need? What do they want? What are their pain points? Will they even use this product or service?

These are some of the questions that UX designers help answer by not only interacting with real, live users (through user interviews and usability testing), but also through documenting user needs through UX deliverables.

There is no “average” UX design process, but if there were, it would probably look like this:

  • Initial research (user interviews; deliverables: personas, wireframes, site maps)
  • Prototyping (deliverable: simple or clickable prototype)
  • Usability testing (deliverable: usability report, customer journey map)
  • Maintenance (post-launch; varied)

At all stages of this process, documentation is created and maintained by the UXer. And the goal of this documentation is to make sure that the product or service being designed meets user expectations.

Naming and framing UX deliverables: final steps for Module #4

General Business

Drafts are overall looking good. Below is some stuff to work on in revision.

Name Your Deliverables Correctly

One of the most important things to do in the UX world is to correctly name your deliverables. For example, several of you are calling what you did a “usability test,” which means that you tested with people outside yourself. If you simply reviewed an application for UX best practices, that’s a “usability review.”

There are a lot of deliverables in UX and they each have different purposes. The modern day design process is very opaque to outsiders and that’s why it’s important to use the right deliverable (and name each deliverable correctly) for the right job.

If you’re not sure what you’ve created, visit here for a complete list of deliverables:

Then, Contextualize Them With Writing

The second most important thing you need to do in the UX world is contextualize your deliverables with writing. UX is just another form of documentation. Many UX people would hate me calling it that, because they think of themselves as “designers” and look down on documentation, but those are not the sorts of people you want to invite to your afternoon tea, anyway.

So, good documentation has to operate by itself. This means if you just made some UX deliverables for this module, but didn’t contextualize what they are or how the audience should use them, think again ;-). You need to think of your deliverables as a kind of technical report to the rest of your design team regarding where you should go next. You thus absolutely need to explain what each deliverable means to your audience.

5) 11/3 by Midnight ET >>

Revise all documents you’ve created. The point of these reviews is to help you improve your writing. Revise, revise, revise.

Be sure you review what your reviewers said about your draft as you work on your final draft, as well as my class-wide response. Listen to your reviewers and make critical choices to improve your documents based on what they say.

Post your Cover Letter and a final draft of your UX Document to Canvas.

Response to Homework #4: I’m a technical communicator. Why should I care about UX?

Business Keeping

Grades will always be posted to Canvas. Check for them there.

I’m a technical communicator. Why should I care about UX?

UX is a very emergent term within technical communication, and I was worried that this module would fall flat because of that.

Let me just summarize why you told me we should care about UX, in your posts and homework responses: because technical communicators are beginning to craft experiences for users, not just documents for readers.

Isn’t UX just usability?

A lot of people ask me this, so I thought I’d speak to this as well. Here’s a representative definition of usability:

Usability is a tool that assesses the ease-of-use of user interfaces, based on its learnability, efficiency, memorability, errors, and satisfaction. Usability isa basic need for organizations. – Gabriella

When we contrast this definition with the more comprehensive one,
we see the problem:

User Experience Design refers to a comprehensive concept as well as a process that examines whether end users interact with a system the way they are intended to. User feedback is a major tenet of UX. User Experience Design is both an art and a science. It is comprised of many parts, such as language, graphics, sound, motion, information, interface interaction, and programming, that all are supposed to work seamlessly as a whole to meet both user’s needs, desires, and goals as well as the publishing organization’s needs, desires and goals. – Gergana

People mistake a part for a whole when they conflate usability with UX. UX is the entire experience a user has, and usability is one aspect of that experience.

Okay, I get it. How should I care about UX?

Hopefully this homework assignment did give you a kind of tool kit for thinking about UX beyond this assignment, and even beyond this class.

Here are some of the individual tools in that toolkit.

  • Conducting a Usability Review

A usability review is an analysis of a website or application that utilizes a persona of the typical user to determine if critical tasks can be completed to achieve the desired goal or outcome of the organization or individual that owns the site. This review provides clients/owners with valuable information that can be used to improve the UX of the site and make it more successful.

  • Wireframing

Wireframing is a very simple method of demonstrating a site’s layout and functionality. By eliminating images, color, graphics, and other styling, it helps designers focus on the ‘bare-bones’ aspects of a site and its space allocation, prioritization of content, functionality, and intended behaviors. It is useful in the UX process because it provides designers with the ability to analyze features of the site for successful navigation and content elements and determine if changes are needed to improve space allocation and content hierarchy. Wireframing can be conducted in low-fi or hi-fi to provide a lower or higher level of detail, with low-fi being a quick and abstract method and high-fi being more detailed and documentable.

  • Card Sorting

Open and closed card sorting is a method of research that provides the designer with an opportunity to gather input from users about how they sort and organize topics and content on a webpage. It can be done with either a paper or computer application, individually or in groups, an in an open or closed sort. An open sort gives the researcher data on how a user categorizes information, and a closed sort provides data on how a user determines which category the information belongs in. This helps the UX process by incorporating user input into the design of the site and aligning it to user expectations and needs.

  • Field Study (before starting the design)

This method of research provides a designer with the opportunity to study users in their own environment and make observations of their behavior when performing the activities that are part of the design. Conducting a field study prior to the design process gives the designer the potential ability to discover valuable innovations for the UX design but can be costly, since there is no actual testing of the design in this method. Changes that have to made after the design is implemented are more expensive than those made early in the design process.

  • Testing a Low-Fi Prototype

This method of research is early in the design process, but after it has begun. It gives the designer the opportunity to test the design on an inexpensive prototype and integrate user input into changes before the design is completed and implemented. Low-fi prototype testing gives the designer the advantage of usability testing without the higher cost that can result when testing to validate a design, since changes made at the prototype stage are less expensive.

Accessibility and including users in your design process

Universal design is considering accessibility and having more than one purpose. Accessibility is more than coding and involves everyone involved in making the website work. Some of the examples improving the user experience are keyboard use, color contrast, and audio video quality. – Jennifer

One of the key things I’d like you get from this homework assignment and module is that if you don’t have real, live users involved with your design process, you are designing in a vacuum. You have no way of knowing how actual people are going to respond to your design unless you get their input. This includes folks with disabilities, who are notoriously excluded from design processes.

I’m not saying you should specifically recruit users who are disabled, but I am saying you should cast your net broadly when recruiting users, and should do everything in your power to make sure folks with disabilities are a representative part of that recruited population.

From UX methods to UX strategy and from use to participation

Business design is a description of how a business works and what process it performs. Business modeling involves defining the customer and their goals, building the map of the business process, and creating the use-cases from these steps. This will help to guide an organization’s improvements through a structured workflow. – Christina

Beyond individual methods, UX experts are beginning to talk about an overall strategy for crafting a digital experience, and how individual methods should fit into that overall strategy. One thing most experts agree on right now is that users should be as substantive a part of the design process as possible, and thus should be thought of as participants, not just end-users.

One thing is for certain: UX is not going away anytime soon. It has stood the test of time through its evolution from usability engineering to UX strategy and more and more businesses, non-profits, and schools are discovering its power. The more you can learn about it, the more marketable you will become as a communications professional.

Editing good all the time: Response to Module #3

Business Keeping

Grades will always be posted to Canvas. Check for them there. You also receive individualized feedback on modules, so be sure to log in to check your feedback to avoid future grade penalty.

We Edit All the Time, Just Not Very Well

If you caught the joke in the title of this post (it should be “editing well,” not “editing good,”) then you have been bit by the editorial bug. Soon you will see wordiness everywhere you look. You will see common grammar mistakes like there/their and its/it’s like glaring neon signs.

Unlike the common conception, most writers have an awareness of editing. We all rewrite status updates and emails before posting or sending them. Well, at least some of us do ;-). Real editors carry around all the rules in their heads, which takes years to learn.

If you want to become an editor, I highly recommend this book, which is a complete rundown of the principles introduced in this module:

The cover of the book Plain Language in Plain English

On Amazon:

If You Want to Be a Content Strategist or Information Architect, There’s a Lot More Involved

Though I meant what I said before that content strategy and information architecture are natural extensions of editing, they are also disciplines in their own right with their own unique skill sets. To me, these two disciplines are more alike than they are different, largely dealing with things like:

  • Editorial strategy
  • Taxonomy
  • Metadata
  • Governance
  • Analytics
  • SEO
  • Content Auditing
  • Content Planning
  • Content Modeling
  • Structured Authoring
  • Customer Journey Mapping
  • Audience Research
  • Persona Development

If you don’t know what any of those things are, feel free to do some research! There are lots of books on these topics, as well. I’m working on one currently ;-).

Editorial Schmeditorial: Final steps for Module 3

General Business

Drafts are overall looking good. Below is some stuff to work on in revision.

Use An Editing System That Makes Sense to Your Audience

The first thing you should look at in your draft is: does this make sense to my audience? Consider things like jargon, terminology, and directions. Your editorial document should direct your audience to do something: to make changes. Is it doing that? Will your audience understand your directions? What won’t they understand? Also: make sure you’re not just doing the changes for them. If you edited a document, that’s fine, but you need to show all the changes you made so the audience will understand what changes you made.

Include a Short Cover Note / Executive Summary of Changes

It’s also important as an editor to summarize the changes you made. This is almost always the case, unless you have a close working relationship with your audience and they know / expect the type of changes you’re making. Your Executive Summary should do the following things:

  • Explain the goals of your editorial changes. How will they improve the document?
  • Give a high-level, concise overview of the changes you made or are recommending. Think categories of changes: grammar, style, text, visuals, etc.
  • Give a brief list of next steps. What does the audience need to do next, based on your recommendations?

Consider Including Screenshots if You’re Editing Something Visually

If you’re doing something like a content audit of a website, I highly recommend you include some screenshots if you’re providing feedback on visual design. In my extensive experience, audiences struggle to understand feedback regarding visual design without seeing something.

5) 10/13/20 by Midnight ET >>

Revise all documents you’ve created. The point of these reviews is to help you improve your writing. Revise, revise, revise.

Be sure you review what your reviewers said about your draft as you work on your final draft, as well as my class-wide response. Listen to your reviewers and make critical choices to improve your documents based on what they say.

Post your Cover Letter and a final draft of your Editorial Document to Canvas.

Response to Homework #3: Maybe content strategy and information architecture are the next tech comm

Business Keeping

Grades on Canvas as usual. Check for them there.

Editing Is More Than a Checklist; It’s a Process

Though a lot of editing does amount to checking writing drafts against style guides, citation systems, Standard Edited American English, and other conventions, editing is really a process. The more you put into place processes and guidelines at the beginning of a writing process, the less work you have to do in the long run. It’s a lot more efficient to get people to follow guidelines than it is to correct mistakes, though admittedly editing always entails both (because people are generally bad at following complex guidelines).

Some important elements to check off when editing technical content include; verifying the style/structure of the final product; verifying that headers/footers are correct; preventing hyphenation of words across two pages; preventing a word less than four letters of being on a line by itself, etc. It is important to establish style guidelines early in an editorial process because it establishes the structure for the project and saves the technical writer’s time by cutting out the guesswork and having to reformat it later if it were not immediately specified. – Gabriella

Single-Sourcing Is Becoming the New Norm

Single-sourcing has changed the way editors operate as the focus now is on creating structured content that can be repurposed. Many editors now function as content managers who assure that content is written appropriately in a structured form and then gets published correctly in a particular channel (i.e. mobile, web, PDF, print, email, etc.). This has greatly complexified the role of technical editors, in particular.

Single sourcing is the process of creating multiple deliverables from one set of files, which goes hand in hand with structured authoring, which is an environment in technical writing that defines processes, design, and style. – Cassidy

Content Strategy Is Growing in Importance

Along with the growth of single-sourcing, comes the growth of content strategy, which is really about creating organization-wide style guides that ensure that all content is managed appropriately. Some content strategists focus primarily on a particular subset of an organization’s content (such as managing structured content), whereas others focus organization-wide to ensure all content (i.e., marketing, technical writing, internal communication, customer service, etc.) serves the organization’s goals.

Editorial strategy defines the guidelines by which all online content is governed: values, voice, tone, legal and regulatory concerns, user-generated content, and so on. This practice also defines an organization’s online editorial calendar, including content life cycles. – Catherine

Some Senior Technical Writers Are Transitioning to Information Architecture

I’m also seeing some senior technical writers make the leap into managing the overall structure of information within a technology, rather than creating or managing content. These folks often start out as content creators and then increasingly move up through the hierarchy of their organizations until they are managing the entire information flow. There is a high learning curve that goes along with this transition, however, because developing something like a site map is very different than just writing content that will be published to an individual webpage. At the same time, however, both jobs (technical writer and information architect) largely draw upon the same broad skill sets: effective communication, good organization, and the ability to translate and synthesize complex information.

Information architecture is the creation of a structure for a website, application, or other project, that enablesus to understand where we are as users, and where the information we want is in relation to our position. Kind of like the menu bar at the top of a website. They create site maps, hierarchies, categorizations, navigation, and metadata. – Brianna

Specking and trekking: Teacher response to module #2

Business Keeping

Grades will always be posted to Canvas. Check for them there. You also receive individualized feedback on modules, so be sure to log in to check your feedback to avoid future grade penalty.

The Importance of Specifying Product Information for Specific Audiences

Product specifications are all around us. We use them to determine the safety, compatibility, usefulness, and many other attributes for products we use on a daily basis. Many of them are written by developers of products however and thus contain a lot of extraneous information not useful for users. Think about a computer. Do you need to know every specification for it? Or just the ones that will affect your use of it? And yet most computers advertised contain a variety of jargon-laden specifications that the vast majority of consumers can’t make heads or tails of.

Sometimes specifications are partially controlled by regulating agencies, but regardless, they should always be designed for specific audiences, not a general, “public” audience. They should provide specific audiences with necessary information not alienate them with jargon.

Why Users Trek Through Documentation

When designing tasks, it’s important to remember why users go to documentation in the first place: to accomplish goals and to alleviate pain points. If something is obvious, then the documentation isn’t needed. It’s when a product fails, when we can’t figure out how to do something with it, or when we are trying to figure out advanced features that we got to documentation.

This is why it’s important to design tasks that deal with common paint points for a product. If you don’t know what the pain points are, you should find out. The best way to do this is by talking to real, live users. You should never just try to document every single task for a product, because that will just create needless documentation that users have to wade through.

Taskmastery: Final steps for module #2

General Business

Drafts are overall looking good. Below is some stuff to work on in revision.

Make Sure Your Specifications Have Something to Do With Your Task

As Pringle & O’Keefe point out, specifications are never written in a vacuum. They aren’t just a list of product features, but rather give necessary information to a particular audience, such as someone trying to use a product in a particular way. Make sure your specifications are necessary for your target audience. Ask yourself: do they give information the audience needs? Are they understandable to the audience? Do they provide important background information for the procedure they’re about to undertake?

Make Sure Your Tasks Are Usable

Before handing in your final draft, go through the actual tasks in your procedure and try them out. Better yet: have someone completely unfamiliar with the tasks try them out. This is the only real way to test a procedure: to see if someone can complete it with just the instructions given!

Worst case, though: go through your tasks step-by-step yourself and try them out. Make sure you haven’t missed anything!

6) 9/22/20 by midnight ET >>

Revise all documents you’ve created. The point of these reviews is to help you improve your writing. Revise, revise, revise.

Be sure you review what your reviewers said about your draft as you work on your final draft, as well as my class-wide response. Listen to your reviewers and make critical choices to improve your documents based on what they say.

Post your Cover Letter and a final draft of your Technical Specification and Procedure Document to Canvas.


General Business

Grades are always posted to Canvas. Check for them there.

Technical Writing Is All Around Us, But Is Rarely Done Well

One thing I want you to take from this class is that technical writing is all around us. Any time we seek to break down complex information to simpler terms for an audience or try to teach someone who to do something, we are doing technical writing. Doing it well, however, is another matter. There is a reason why technical writers are highly-paid professionals who only get more valuable as they gain experience. Companies that hire them know that someone who can communicate complex information in an understandable manner to core audiences, both internally and externally, is worth the money.

Prior to reading this text, I thought that technical specifications were basically just the specification of the hardware. For example, if I build a computer, the specs would be the processor speed, type of RAM, video card specs, etc. If I installed a game on the computer, the specs for the game would be the system requirements to run the game. After reading this, I see that I was a little bit on the right track, but the term actually encompasses much more than I thought it did. The specs also include component illustrations and information about those components, lists, features, and even schedules for the product. A spec can be beneficial because of all the information it provides, but they are also rarely accurate because they are not updated often. Apparently really good specs are so rare that if you find one, you’ll be so rich that you won’t have to work again. – Tamara

Technical Writing Is All About Cross-Functional Teamwork

Another thing I want you to get is that technical writers never work alone. They are jacks and jills of all trades that work with SMEs, developers, managers, editors, and other writers. They are good at interviewing, writing, editing, audience analysis, and a host of other skills. They are proof that writing is inherently social, in other words, despite what the mythos of literary history tells us about the lone writer composing the next great genre by him or herself.

Developers and subject matter experts (SMEs) are important in the technical writing process because they are going to be the most familiar with the subject/product being writtenaboutand are able to provide information about the productthat the technical writer may not otherwise be privy to. Interviewing them is crucial for technical documentation to maintain accuracyon product specifications and functionality, as well as knowing when to write specific sections of the technical documentation based on where the product is in development. – Gabriella

Symbolic-analytic work is the process of problem-solving for given information (also known as distributive work). Technical writers can help with the understanding of this form of work. Along with how individuals process this kind of work by examining the study of writing. Coordination of symbolic-analytic work is also key to the understanding. Technological and rhetorical skill are also key components of technical writing that corresponds with this kind of works. – Emily

What We Call “Technical Writing” Is Actually a Zillion Little Sub-Genres

Another difficult thing to grasp about technical writing is that it is best described as a large collection of sub-genres. Organizations employ technical writers because they provide a wide variety of sub-genres of writing. Whereas once upon a time, this might have simply been procedural manuals, the field has now exploded to cover everything from functional specifications to blog posts. Technical writers are responsible for such a wide array of genres of writing, in fact, that it’s impossible to describe all of them. Some are very short-lived and exist within specific organizations. Some, like procedures, are more global but are still driven by the goals of individual organizations.

The different types of content found within technical documentation are:

a.) Interface Information- explains the function of a particular part on a product.

b.) Reference information- data readers need to look up or reference.

c.) Conceptual information- Providing the “why” behind a feature.

d.) Procedural information- steps that tell a user how to perform a task. – Jennifer