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 explain 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 dull. Boring is bad for conversation or novels, but boring is clear. Clear is excellent for programming, to-do lists, and tasks.
I’ve taken my version of CRUD and swapped an M for the R. I think the acronym breaks down now, but now I can Move things! Examples:
- Create a new menu item in the nav
- Move the H1 text 200px lower
- Update the brand color to the new blue (included)
- Delete the post about time travel (link included)
Be Imperative
Remember way back in early high school or even 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. Alternative moods 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? Personally, I’d rather go through a list of tasks or TODOs.
Combine the simple but straightforward verbs with the imperative mood to remove ambiguity from your reader’s mind. As a rule of thumb, reread your 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 will require some back-and-forth to understand precisely what is being asked. Be clear upfront.
Be Descriptive in the Description
Try to keep the task title as succinct as possible. Use the “You, do this” tone. Once you have a format, it won’t convey any other meaning besides the “I respect your and my time. I’m keeping this as simple, clear, and succinct as possible” message.
Every task manager or shared to-do list I’ve ever used has room for a description or notes about the task. This is where you add the supporting details. Recall 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 card, which 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 handy when these tasks persevere in some systems. A screenshot is worth a thousand words but can’t replace all text. The text helps search later. Sometimes, you can’t remember a task, and 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 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 helpful to do so. You’ll know when that is.
Share a link to your screenshot for fast uploads or something that doesn’t need to persevere for a long time. Upload the image file to your task system whenever you need to keep something in the archive 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 to screenshot applications. There are many reasons 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, you must provide vectors that match 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 progress. Here is an example of a list of links for QA
- [ ] https://google.com
- [ ] https://maps.google.com
- [ ] 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, they will be taken directly to the element. This can be useful when QA in any form. It’ll reduce a lot of scrolling.
Along with linking to the pages in question, link to resources that someone may find helpful. 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 concise. Use the description to add context to the title. Guide someone to the exact location with plenty of valuable links. Links should include the “where” but can also include the “why.” Above all, you should treat your colleagues and company with respect. You value their time, so don’t waste their, yours, or the company’s time 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, it would be easier to rediscover what you were thinking. You’ll have links and support docs like annotated screenshots to jar your memory.