Approaching projects - Part 6 - 2021-11-11

Do you have a project, a skill, a goal you'd like to complete or progress? Are you on your own, lacking leadership and structure, or could use more of it for yourself and your team? Here's what I've discovered works for me as a solo software developer and later as an engineering manager. This is a series of posts, the next post part 7 on executing the plan comes next.

In the last post Approaching projects - Part 5, I described that creating a plan involves an approximate simulation of what will be executed. This post will focus on documenting the steps that will be executed.

Throughout this series of posts I will be using this user story: As a person with money, I want a custom computer desk to fit in a weird spot in my home. With the chosen solution: Build the desk myself.

Documenting a plan

When you are confident that:

Then it is time to create tickets. Tickets, issues, tasks, stories, there's several names that overall mean the same thing when put into some software tracker.

Oddly even "bug" may be used in some organizations for a work item. I specifically hear this from an ex-googler who did encrypted packet routing for the google cloud platform. Their system is called Buganizer, so all things were "bugs".

Now sure, maybe this is a pet project for you, so a nondescript ticket body would be fine if you addressed it within the week. But have you ever left yourself a note like "fix" on the fridge and a month later you don't know what needs to be fixed?

A poor example of a ticket

How about another

A poor example of a ticket

Your goal at this stage is to get the complete picture outside of your head. Why? When you dive back in to perform or oversee these tasks, you won't have the head space for this anymore. Writing good tasks is about setting your future self (and team) up for success. So when you write a task, take the time to produce a closure of your ideas as it relates to the scope of a task.

Ever use a lambda in Java or C#, where final or immutable variables could be referenced inside? So, a closure is essentially a function plus an environment. Variables declared outside of the function definition are part of the environment. So when the lambda is constructed, it contains the function definition plus a snapshot of the environment relevant to execute it. Often, these variables are final or immutable because a lambda function may be executed on another stack and therefore lose access to the variables referenced. An immutable snapshot preserves the intent of the function as it was prepared for execution. There are ways to work around it.
There are some neat things done in other languages where the lambda is guaranteed to run within the same stack and can therefore mutate the referenced environment.

So let's start with the function. Take for example a segment from the last post, specifically the task on routing the table surface so that it had beveled edges. I'll refactor it so it so the resources and process are preserved

class Plan {
  void routeSurface(
    Router router,
    RouterBit bevelBit,
    WoodSurface sandedSurface) {
    // Route each side of the top of the table
    router.route(sandedSurface); // Left
    router.route(sandedSurface); // Right
    router.route(sandedSurface); // Back
    router.route(sandedSurface); // Front

The code above provides a simplified "proposed solution", it references which resources are needed, and it has a hint of the overall intent inside.

Next, let's consider the environment, the context that this is happening within. Put in context, we know that it comes after sanding the table surface. We should also ask why this section of the plan was included. How does it relate to the story? Traveling back in time (a prior post), we can see that in the requirements: It should be beveled along the edges so that it does not cut at the wrists.

Some points can be collected from these observations

Let's review a good example of an issue and see how this list holds up.

A good example of a ticket

On this AWS CDK enhancement request, we see:

Let's look at another, an issue or bug

A good example of a ticket

See how these ticket contributors are communicating the context, the motivation, an idea of what to do, and some research? The greatest thing a ticket can do is set expectations in context.

These expectations may be in the form of reference interfaces, JSON request bodies and JSON response bodies, or other specifications. Effects like This phone number should receive a text message with ..., Calculations like The total payroll amount should include the total of all shifts performed with an appropriate hourly rate plus bonuses and ..., the list and examples can go on. In fact, include examples!

Some examples will become test cases for QA, used as unit test material, and so on. Examples and logical expectations set the acceptance criteria of a task. With logical expectations like If I have two numbers in this list, then the same two numbers will receive this text message may then expand to five or ten or whatever limits are set. Clarification may be requested on limits which another type of expectation.

Example task

Let's make a task for this table top routing.


After sanding a completed table top surface, the table top surface is ready to have it's edges beveled so all areas normally touched are smooth and do not splinter. Beveling with a router will add a curve along the sides of the surface so the palm can smoothly roll over it. A router can only bevel if a proper beveling bit is installed. I think that 1cm of depth would be sufficient.

Afterwards I should be able to roll my hand from the side to the surface without discomfort.

Use Case

As I use my computer desk, I want to comfortably slide my hand from the arm rests to the keyboard when I'm ready to type. Also, I wish to be able to move my wrist from the keyboard to the mouse without much friction. I find that beveled surfaces allow me to do this comfortably, while edge cut surfaces do not.

Proposed Solution

  • Load the router with a beveling bit
  • Route all for sides of the top surface so that it is beveled

Other Information

"Beveling" might be the wrong word, round over edge seems to be what I mean.

Is blocked by The task for sanding the surface.

You're the expert

At the time of writing the task you are the expert. Share your knowledge with your team and your future self. Readers of a task should become familiar enough with the material context to execute and resolve it faithfully without the stakeholder being proactively involved. Sure, some clarification can and should be requested but later on that expertness on you may fade. Especially if you're doing this on your own and performing multiple roles.

Of course, you may come to a task written a month ago with new knowledge and a task's expectations or motivations are no longer accurate. That's fine! It happens. Take the time to cultivate tasks so they are coherent and in harmony with the greater vision of a project. However that's getting into the next topic!

The main takeaways of this post are:

This post is the sixth of the series, part 7 on executing the plan comes next.

You can succeed! When designing a large project, you are the expert. Preserve your knowledge, the context and experience you've earned into these tasks. You and your team will work smoothly when you're of one mind and goal.