Approaching projects - Part 6

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:

• You understand the User Story
• A proposed solution satisfies the story
• The proposed solution is possible
• Milestones for the solution are defined
• You have models and references for steps that support each deliverable
• A reasonable sequence and dependency graph of steps to create each deliverable is drafted

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?

How about another

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.loadBit(bevelBit);
    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

• A proposed solution, if available, should be included
• Resource needs should be documented
• Configurations of resources should be documented (e.g. loading a bevel bit into the router)
• Post conditions / acceptance criteria should be included
• Dependencies on other tasks should be documented and linked
• Preconditions should be included too (e.g. the table surface must be sanded)
• The external requirement and story should be included
• Any additional context or research may be of help

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

On this AWS CDK enhancement request, we see:

• A user story under "Use Case"
• Example code of how it would be used under "Proposed Solution"
• Links to related issues
• Links to knowledge resources (research)

Let's look at another, an issue or bug

• A user story under "What is the problem?"
• Example code under "Reproduction Steps"
• Post Conditions under "What did you expect to happen?"
• Context on current behavior for "What actually happened?"

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.

Description

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

homesteady

For your privacy, this youtube video was not automatically loaded.
Click this area to load an embedded youtube video.

Home Remodeling Tools : How to Round Edges with the Handheld Router Monday, Jan 9, 2023

"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:

• A good task sets expectations in context
• Tasks dependent on something else should say so
• Resources required should be mentioned in the writing
• A good task represents the stakeholder's desires and interests, so the task can be performed without the stakeholder's proactive attention
• Tasks are your chance to preserve your knowledge where it matters most

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.