Skip to content

Write how much work is required, not the work itself

Erica Pisani
Erica Pisani
1 min read

The format for outlining what work needs to be done to achieve an outcome varies from company to company.

It can be challenging to convey a sense of scope when writing what work needs to be completed, and the result can sometimes amount to ‘do X so a user can do Y’ with the hope that the developer doing the work understands what the writer is getting at or to have a sense of who to ask follow up questions to if they’re unsure.

Writing as a skill has always been important, but as workplaces become increasingly distributed, it’s even more crucial.

Misunderstood Github issues, Jira tickets, or however work is tracked, often leads to wasted time and effort. It also makes onboarding new developers difficult as they won’t have a sense of where pieces of functionality live within a codebase.

Some companies use templates for outlining different types of work such as features, bugs, and chore work (e.g: data migrations), but at others - particularly smaller companies with no formalized process - the format used depends on the individual writer.

A senior developer on a team I previously worked on proposed during a estimation session that instead of writing what the work itself is (“do X so a user can do Y”), we should instead focus on writing how much work is required.

For example, this change needs to apply to X amount of files, and some of these are frequently used code paths with no test coverage so manual testing will be required.

By focusing on how much work is required when writing what work needs to be completed, we can get a better sense of the scope of changes needed to accomplish a desired outcome.

While there will still be gaps in knowledge and work missed when following this format, this tended to give a better sense of scope of the work, which in turn helped feed into better estimations for project planning purposes, and improved the onboarding experience for newer developers on the team.


📫
Enjoy this post? Subscribe to be notified when I publish new content!
tips-and-tricks

Comments


Related Posts

Members Public

Git Log's Hidden Gems: Using -S and -L for Powerful Code History Search

Ever needed to track down when a specific piece of code was first introduced in a project? As part of some refactoring I had to do recently, I needed to do just that for a variable on a Django model. I was already familiar with the basic git log command,

Git Log's Hidden Gems: Using -S and -L for Powerful Code History Search
Members Public

Using XOR to write concise conditionals

It's not uncommon that I sometimes write if statements where the overall conditional is true when both conditions are true or both are false. As an example, let's say I'm validating input from an API call where I'm updating information on a

Members Public

Fixing "No preset version installed for command poetry"

Poetry is a packaging and dependency management tool for Python, and a tool that didn't exist when I worked with Python many years before I started working at Float. I also hadn't been exposed to asdf, which is a handy little tool for managing multiple runtimes.