A Document for Freelance Front-end Developers

A little about communication

Communication is hard. Complex thoughts arise within an individual, individual A. Those thoughts are then encoded by individual A, using language. Those encoded thoughts are then absorbed, amidst an array of noise, by another individual, individual B. That language is then decoded by individual B, into complex thoughts, hopefully the complex thoughts that first arouse in individual A. Both parties are engaged equally in this communication process, and therefore, are both responsible for ensuring that this communication is successful.

“The client was not tech. savvy.”

A feckless excuse that I have heard thrown around, a little too often, when a project fails or a client is not satisfied with what was delivered. My understanding is that a client hires technologists because they, themselves, are not tech. savvy. I don’t believe that a client’s technical understanding should be directly correlated with the quality of the product that is delivered to them by hired technologists. It’s the technologists responsibility to guide the product development process, as well as, guiding the client through that development process.

I must admit, I have had my difficulties communicating with clients, but I want to take responsibility for my portion of our communication process. That’s why I wrote the following document while freelancing as a front-end developer. I hoped that this document would help clients understand my development process, while defining some jargon, and decrease the probability of miscommunications between my client, and myself. The document outlines a flexible retainer idea that I test drove with one of my previous clients. I hope that others can find my document interesting, enlightening, or most importantly, helpful.

The Document

There is a phrase I hear thrown around quite often: “ … has experience communicating with engineers …” As if communicating with an engineer or developer is some skill that must be attained only through experience. Unless, you are born with the the fabled, innate ability to communicate with engineers — called developer tongue in some parts of the world — your process will be riddled with miscommunications and frustration, which I have seen happen time and time again.

I believe that it’s the engineer’s responsibility to communicate what they need from clients to work efficiently, and that is what I hope to provide in this guide.

About this document

This document outlines a general process, and set of best practices, that I have found through experience, to facilitate a clear, efficient, and gratifying working relationship, for myself that those that I work with. I must acknowledge that every project, every relationship, and every communication pipeline is different. With that said, I want to reiterate that this document is to be used as a scaffolding, and not of a rigid construct.

1. Reserving Hours

Hours are reserved for the upcoming week by Thursday evening.

2. Defining Tasks

Tasks are provided for the upcoming week. These tasks include, but not limited to, bug fixes, features, and stylistic updates.

Features must be accompanied by clear requirements, see Requirements for a Feature below. If they are not I cannot provide an accurate estimate, and further, will not be able to implement that feature.

I understand that it’s not always possible to precisely define all requirements for a particular feature. With that understanding any time spent resolving ambiguities via discussion, or any adjustments that must be made, will be billed at an hourly rate.

3. Estimates

Estimates for the defined tasks are provided Thursday evening or Friday morning, the week before the work is to be completed.

4. Discussion

Naturally there will be a discussion following those steps. During this discussion details about tasks, allocated hours, and timing will be discussed. This discussion should be had the week before development begins. I can’t guarantee I will be able to complete this work during the coming week, if that work is not defined before that week begins.

For example, if we have allocated twenty hours of dedicated development between February 15th to February 19th, for one feature, and we are finalizing the requirements for a feature on February 18th, I cannot guarantee twenty hours will be available between the remainder of February 18th and February 19th.

6. Agreement of Details

After discussion we will have reached an agreement on the number of hours allocated, and a list of tasks to be completed with well defined requirements, for the following week. This will be communicated in a legally binding communication, ex: an email.

5. Work begins

Finally, work will begin. I must reiterate, the entirety of this process should be completed the week before work is said to begin. Otherwise, I cannot guarantee that the allocated hours will be available.

6. Scrum

Every morning I will post updates in Slack, describing the work I’ve completed the previous day, and the work expected to be completed on that day. Along with the number of hours spent the previous day, and the total number of hours spent that week.

This will open a micro-discussion around the weekly progress, and adjustments to tasks, and or requirements.

Why accurate estimations are important.

Parkinson’s Law (Software Engineering)

Over Estimation

Estimate a job will take 12 months, but the project could be comfortably completed in 10 months… But it will be completed in 12 months.

+ 20% you will not notice the extra time.

Under Estimation

Estimate a job will take 8 months, but the project could be completed in 10 months… Because of the shortcuts it will take 12 months to complete.

You will notice, and it will take extra time.

Requirements for a Feature

What is a feature?

A feature is defined by the IEEE 829 as “A distinguishing characteristic of a software item (e.g., performance, portability, or functionality).” — Wikipedia

For me to provide an accurate estimate, and to implement a feature, I need an unambiguous understanding of that feature. Natural language is ambiguous by nature, therefore I want to provide some suggestions to help provide clarity for a feature.

Visual aids

A mock up of a feature, that includes guidance for all viewport sizes, and states.

Viewport sizes may include:

  • Mobile, (small screens, not necessarily a phone)
  • Tablet (medium screens, not necessarily a tablet)
  • Desktop (large screens, not necessarily a desktop computer)
  • TV (extra large screens, not necessarily a television)

States may include

  • Success (some action has been completed successfully! Hooray!)
  • Error (something went horribly, horribly wrong!)
  • Blank Slate (there’s no information here, let’s provide some encouragement!)
  • Hover, Active, etc. (visual feedback to something a user is doing.)

User Stories

To implement a feature correctly, an engineer must understand, generally without a doubt, how the feature works, and where it is displayed.

Since computers are mathematically driven, they require precise instructions from an engineer, provided in the form of computer code. For an engineer to provide precise instructions, they must have precise instructions from you.

A great way to communicate this is by explaining the feature from a user’s perspective, called user stories.

Example user stories

  • When a user {arrives at the homepage}, {for the first time}, {a banner notification is displayed}.
  • When a user {enters their username}, {without a password}, {they are not logged in}, an {error message is displayed at the top of the screen}, and {the password field is outlined in red}.
  • When a user {clicks “Samples” in the Main Navigation}, {they see a list of samples with an adjustable quantity for each order}.
  • When a user {chooses a quantity greater than two}, {the change will be prevented, or reverted}.
  • When a user {is satisfied with their selection}, {they will click the “Add to Cart” button}, and {will be redirected to the shopping cart}.


Scrum is an iterative and incremental agile software development methodology for managing product development. It defines “a flexible, holistic product development strategy where a development team works as a unit to reach a common goal”,[1] challenges assumptions of the “traditional, sequential approach”[1] to product development, and enables teams to self-organize by encouraging physical co-location or close online collaboration of all team members, as well as daily face-to-face communication among all team members and disciplines in the project.

A key principle of scrum is its recognition that during production processes, the customers can change their minds about what they want and need (often called requirements volatility[2]), and that unpredicted challenges cannot be easily addressed in a traditional predictive or planned manner. As such, scrum adopts an empirical approach — accepting that the problem cannot be fully understood or defined, focusing instead on maximizing the team’s ability to deliver quickly, to respond to emerging requirements and to adapt to evolving technologies and changes in market conditions.


Final Note

I hope that this document can serve all parties moving forward.

Kindest Regards,

Jeff Powers

Like what you read? Give Jeff Powers a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.