All posts by admin

Documenting documentation: final steps for final project (Due 11/23)

General Business

Drafts are overall looking good, though some of you forgot to submit to Canvas. Don’t worry; I just looked at your drafts on the course site, but your individual feedback is on Canvas. Be sure you read it. I’ve given everyone specific suggestions for revision. Below is some stuff everyone can work on in revision.

Make Sure You Have All of Your Deliverables!

Just like real documentation, it’s easy to forget some of your deliverables (which is why you need a doc plan :). Be sure to review the project specs on the final project page (i.e., executive summary, doc plan, persona, etc.)!

Include a Doc Plan Like You Mean It

Several of you didn’t include a full doc plan, which includes dates and deliverables. This is training in how to do a doc plan, so be sure you do that for the final draft. Again: these are mostly of use on more complex forms of documentation, but you want to show that you can do one!

Watch Out for Jargon

Make sure your documentation doesn’t include any terms your audience persona wouldn’t understand. To be sure of this, read through your documentation one last time as your persona and watch out for any terms you think they wouldn’t be able to comprehend at first glance.

Be Concise

Make sure your documentation doesn’t include any excess words. Read through one more time and see if there are places you can trim unnecessary words.

Make Sure Your Visuals Actually Visualize

Also, look through your documentation as your persona and ask yourself: would your persona be able to comprehend each and every visual? If not, there are two options: add a caption to explain the visual or (better) include a visual that is easier to understand.

Documents You Must Produce for this Project

The following must be posted to Canvas by midnight on Monday, 11/23/20:

  1. Cover Letter, which should answer the following questions a) what have you learned about the processes of technical communication in this class? b) what have these processes taught you about your roles as a future writer within a specific career?
  2. A copy of your final project, including all the materials listed above

To Complete This Project (Suggested Workflow)

  1. Don’t forget to follow the best practices you have encountered and researched throughout this class. Revise your final project based on the feedback you’ve received throughout the class.
  2. 11/23/20 by midnight >> Final project due to Canvas, including all materials listed above

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