How to Write a Good Task at Work

If you write a good task at work it can save your team a lot of back and forth discussion time trying to suss out what you actually meant with the original sentiments. I’ll take you through why sticking to the basics is better than being artistic when you’re involved in an asynchronous conversation where you’re guiding someone exactly where to go. I’ve written about communication at work before, but let’s get into some details here.

Simplify your verbs

Programmers often refer to CRUD when talking out their application logic. CRUD is an acronym for Create Reuse Update and Delete. These four verbs will take you a long way. Challenge yourself to only use those four in your day-to-day. Could you get by with just those words? I bet you could but the language would be rather boring. Boring is bad for conversation or novels, but boring is clear. Clear is excellent for programming, todo lists, and tasks.

I’ve taken my own version of CRUD and swapped an M for the R. I think the acronym breaks down at this point, but now I can Move things! Examples:

1. Create a new menu item in the nav
2. Move the H1 text 200px lower
3. Update the brand color to the new blue (included)
4. Delete the post about time travel (link included)

Be Imperative

Remember way back in early high school or even back to middle school English class when the teacher taught us about the Imperative Mood. Well here’s a refresher if you can’t recall that deep.

The imperative mood is to command, basically. Alternative moods would include declarative; stating something and Interrogative; asking a question. These are not as useful in a task list. There is also the implied you. Sometimes denoted with a lower case you in parenthesis like this example “(you) Delete all H2s”.

I think there is sometimes a call for extra politeness in written communication and don’t get me wrong being polite is better than being commanding. After all, how would you like to march your way through a list of commands? I’d rather go through a list of tasks or TODOs, personally.

Combine the simple, but clear, verbs with the imperative mood to remove ambiguity from your reader’s mind. As a rule of thumb, reread your own task. Do you know exactly what you’re referring to? Could this be confused by a reasonable person? Let’s look at some examples.

Bad: Font is yellow

Good: Update the yellow font to the standard white

The bad example is simply stating something. Presumably a fact, but without one of the simple verbs and the imperative mood, it’s going to require some back-and-forth to understand exactly what is being asked. Be clear up front.

Be Descriptive in the Description

Try and keep the title of the task as succinct as possible. Use the “You, do this” tone. Once you have a format, it won’t convey any other meaning besides “I respect your and my time. I’m keeping this as simple, clear, and succinct as possible” message.

Every task manager or shared todo list I’ve ever used has room for a description or notes about the task. This is where you add the supporting details. Recall back to my example in the previous section about changing the yellow font to white. Use the description to add the exact yellow that you’re referring to. There may be an application-wide yellow and that would be nice to include here. If you don’t have time to include the yellow make sure you specify that the application-wide yellow is the one you are referring.

This is an excellent location for screenshots. Make heavy use of a screenshot app and have it ready and chambered at all times. This tool is particularly useful when these tasks will persevere in some type of system. A screenshot is worth a thousand words, but it can’t replace all text. The text is useful for search later. Sometimes you can’t remember what a task was about and be searching by images is yet ready for prime time. Use the screenshot to support the text and not the other way around.

Good screenshot tools should have two main features; annotation and sharing. The screenshot functionality built into your Mac is not good enough although it is free and well built-in. You will take your screenshot but then immediately mark it up with a highlighter or boxes and text. Ensure that this is clear as well. Don’t clutter things. Keep colors consistent throughout your team. Only break away from the hot pink marker and highlighter when it’s useful to do so. You’ll know when that is.

Share either a link to your screenshot for fast uploads and or something that doesn’t need to persevere for a long time. Upload the image file to your task system anytime you need to keep something in the archive for longer. The reason for this is you may go away someday. Or your storage may fill up someday on your screenshot application and your precious image may get deleted. Or you may want to switch screenshot applications. There are many reasons here why a service you use today, isn’t necessarily what you want to use tomorrow.

Guide the Reader

Now that your language and description are satisfactory now you must provide vectors to you exactly what you’re referring to in your task. Use links all of the links that you can. Identify the links with ordered lists. I like to add some simple markup alongside my ordered lists so the user has a premade checklist to use and track her own progress. Here is an example of a list of links for QA

1. [  ] https://google.com
2. [  ] https://maps.google.com
3. [  ] https://www.facebook.com/#userNav

Aside: my little “[  ]” are a light-duty status. “[ / ]” means started and “[ x ]” means complete.

Notice the hashmark in number 3. That hashmark corresponds to an HTML div on the page. When my user clicks that they will be taken directly to the element in question. This can be useful when QA any type of form. It’ll reduce a lot of scrolling.

Along with linking out to the pages in question, also link to resources that someone may find useful. For example, if you are submitting a task to increase the contrast of text on a page, you should provide links to contrast calculators and minimum contrast requirements of your site. Chances are you were referring to those links earlier when you were mulling over this change anyway.

Summary

Keep titles short, consistent, formatted, and succinct. Use the description to add context to the title. Guide someone to the exact location with plenty of useful links. Links should include the “where” but can also include the “why”. Above all treat your colleagues and company with respect. You value their time so don’t waste their, yours, or the companies by being unthoughtful with your writing.

Bonus Tip:

Write for future you. You will need to refer back to this in the next few months. If you used plenty of text to search for it will be easier for you to rediscover what you were thinking. You’ll have links and support docs like annotated screenshots to jar your memory.