Write how much work is required, not the work itself

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.