How to be a Good 508 Engineer

How to be a Good 508 Engineer

How to be a Good 508 Engineer

Author: Caleb Rogers

After I got featured on Teddy Lai's Youtube channel in an interview, membership has exploded. We now have around 60 members, up from the 15 or so we had before. Previously, I was able to one-on-one mentor people into the "508 style" of engineering, but now I think it's best to start with a primer, and from there mentor people into our style as needed.

Being a good 508 engineer (and a good engineer in general) is more than just programming. In fact, the actual code itself is one of the less important defining aspects of a good engineer, in my opinion (and that's why I'm not worried about AI taking our jobs anytime soon). More important than that is soft skills, time management, product sense, communication ability, common engineering sense, and knowledge of best practices.

To help make sure our own internal projects go well, ensure we can deliver consistent quality to our clients, and to help our engineers grow themselves professionally, I'm going to define these skills, as well as ones that deal with coding itself.

Important Soft Skills

Soft skills are everything around code: communication and interpersonal management.

Time Management

This gets the top spot because I think it's one of the most important aspects of an engineer's life, personally and professionally. Time management is also the biggest miss I see in engineers from every skill level. The best senior engineer isn't all that useful if they constantly miss deadlines, forget to complete tasks, or get frequently distracted and work on low-priority tasks.

As someone with ADHD, this issue is particularly close to my heart. That said, my ADHD has been something of a gift, as I've honed my time management and organization skills to a machine. Maybe not a well-oiled one, but at least I'm more systematic in this than almost anyone else I've met (though I've read about other people with way more advanced systems than mine!). I've written about this whole system , but I don't recommend people go this route to start, instead doing something much simpler.

In short, when sitting down to work, a good engineer needs to be able to answer 3 basic questions.

  • What am I working on next?
  • What am I working on after that?
  • How do I find out, or who do I ask, what to work on after that?

The easiest way to know what to work on next is to have it written down, probably in a TODO list. The easiest way to know what to work on after that is to have it written down, either in the same TODO list, or in some kind of project management solution, such as a kanban board. The easiest way to know what to work on when you aren't sure what to work on is to have clearly defined the answer to this question before a project begins; we'll get into that more later.

I've noticed that for many people, the answer to these questions is "I don't know, I'll just wait until someone tells me what to do." That's expected when in a degrading work situation where you don't have any ownership over your labor, such as in large companies. However for freelance engineers or co-op engineers, ownership is the price of freedom. I think in the long run, it's liberating, but at first it can be intimidating.

Practically speaking, the simplest thing to do is have a cheap notebook and a pen or pencil. Throughout the day, instantly write down any tasks as they arise onto this notebook. Don't bother with prioritization or organization, just write every item on a new line. As you complete items, cross them off. Simple.

At the start of every day, grab a new piece of paper and transfer any incomplete tasks to your new paper. There, you now have tasks that weren't done yesterday that maybe need to get done, or worked on, today. You'll add more tasks to the paper throughout the day, and continue this process.

For some people, it might help to define a set of hours where the only thing you're allowed to do is work on items on the list, eat, or go to the bathroom. For example, if you have a crippling League of Legends addiction, you can say, "until 5pm, I can't play LoL, I can only do items on the list." This is how I broke a similar addiction I had to reddit, over time.

This skill is critical to being a good freelancer because if you don't get things done, and done on time, you don't do poorly on a performance review, or get scolded by a boss, or relegated to a new department; you just lose a contract, and don't get new contracts. You also might face embarrassing conversations with a client when they ask why something isn't done yet when it was estimated to be done a week before. If you can stay on your tasks, and have a written history of what was being worked on, you can give a clear answer; perhaps unexpected issues with libraries, undocumented APIs, bugs in client code, or whatever else. Without a good task management system, though, you have no answers, and clients will assume the worse (wasting their money playing League of Legends).

If the paper method gets too restricting, you may want to investigate more advanced methods, such as an online tool such as Google Calendar Tasks, Todoist, Thunderbird Tasks, or Emacs Org Mode for the super advanced. You may also want to look into more TODO management frameworks. The one I like is "Getting Things Done", but there are others.

Personal Responsibility

This one is important enough to get a mention on our values page. Personal responsibility is tied closely into time management, but it expresses itself other ways too.

A key thing to remember as a freelancer is that someone is paying you to do something because they don't know how, don't want to, or don't have time to. Sometimes freelancers fall into a mode of thinking where the client is their boss, but it's a completely different dynamic. At work, your boss is responsible for you, your work, your time. It's fairly normal to have conversations with your boss about implementation details, random code questions, documentation issues, or advice. When you're a freelancer, any time you bring a problem or question to your client, you're decreasing your value to them in the relationship. They hire you to make their problems go away; how do you think they feel if you bring those problems right back to them?

If it was easy, they wouldn't pay us to do it. The work they give us will be hard, and it's up to us to solve whatever problems come up along the way. Unlike at work, where if work gets too overwhelming, your boss can help distribute it to other teammembers, if things get overwhelming, there is nobody there but you to find a solution (unless you're in 508, in which case you can try asking other co-op members for help or advice).

This is a key skill for any engineer, regardless of if they're freelancing or not, and is one of the more frequent questions I get from juniors: how do you know when to ask for help? It's not necessarily bad to ask for help, the important thing is just making sure you did your due diligence, and took personal responsibility for your work, before doing so, especially if the person you're about to ask is your client.

With ADHD, my brain wants the easiest answer, at all times. My instantaneous instinct when coming across and obstacle such as a somewhat difficult block of code, or difficult to implement solution (happens every time I need to implement authentication!) is to get extremely sleepy, distractable, annoyed, and wanting to "offload my mental RAM" onto someone else. The instinct is to immediately ask someone else, which is really just making it someone else's problem.

I have thus developed a set of steps I require myself to go through before I ask for help, especially from a client.

  1. Stare at the code for a decent amount of time, no matter how unreadable it is.
  2. If dealing with libraries or certain functions, ensuring to look at implementation details, methods, arguments available to a function, or other functions or components available from a library.
  3. Flip around some other files, some other places a given component is used, the UI itself (if ui code), or any other parts of the code base that might illuminate more info about the issue.
  4. Read any relevant documentation. If dealing with a library, looking at examples of their implementations.
  5. Google the issue I'm having.
  6. Stack overflow the issue I'm having.
  7. Ask ChatGPT questions to help me define the problem better (ChatGPT solutions themselves are almost never good and often are rabbit holes).
  8. Go for a walk, then repeat all the above steps.
  9. Do something else for a significant amount of time, then repeat all the above steps.

After I complete these steps, I consider myself having fulfilled my personal responsibility. Doing these helps avoid an embarrassing situation where a client issues a single line PR with an obvious fix, or linking a page of documentation that clearly explains the solution. You never want a client doing your job for you! They'll start wondering why they're paying you at all.

Another way this manifests is taking responsibility for any mistakes you make. They happen, everyone makes them, but if it happens to you, it's important to immediately and earnestly take the burden of fault. This can usually lead to better outcomes than trying to defend yourself, blame bad documentation, bad libraries, or an incommunicative client, even if it really is the fault of these things! A good book on this subject is "How to Win Friends and Influence People" by Dale Carnegie, a book I recommend everyone to read at least once in their life, even if they aren't trying to be co-op or freelance engineers.

Project Management

My goal is for every 508 engineer to also be a project manager. This skill is tied tightly into the previous two. At a big corporate job, a project manager manages your time and energy for you, but when you're freelance or a co-op member, it's your responsibility to manage a project and your time. Even if there's someone else acting as project manager on the project you're on (such as the engineering lead), it's important to have at least the basic skills.

Project management manifests itself in many ways, and it's a full career for some people for a reason. For 508, it means having a clear plan, regularly updated, that accurately communicates at any given moment some specific information in a project:

  • What will be worked on
  • What is being worked on
  • What's already done
  • What can't be worked on right now, and why

I prefer to represent this information in a Kanban Board. The columns could be "TODO", "DOING", "BLOCKED", and "DONE", for example. Having this information allows everyone, including clients, to be able to look at a kanban board, and say things like "hey, I noticed the account delete feature isn't on the board, are we covering that?" Or, "I have some new information about this feature, I can see that Mei-hua is working on it, I'll go talk to her about it."

Project management requires whatever system being used to be updated at the start and finish of any task, as well as checking in on its accuracy on a daily basis, with large overviews preferably weekly (e.g. "do we still want this feature, given what we've learned this week?"). This doesn't necessarily mean that daily standups, a standard AGILE ritual, are required. In fact, with a project management system managed to the level that 508 expects of its teams, a daily standup is redundant: every team member can know what they need to work on by simply consulting the board on their own. This ties into them maintaining their own personal responsibility and time management systems.

A good, regularly updated project management system has other advantages. Tied into a good time-tracking system, such as org-mode or kimai (508 has a kimai deployment available for members to use), it allows teams to report exactly how much time was spent on any given issue, which is a nice thing to offer clients interested in itemized invoices. It also allows pinpointing issues that are too big and should be split into smaller tasks.

Even without time-tracking, a good project management system means that a client can at any given moment see exactly how a project is going, giving them peace of mind. It assures them that we have taken responsibility for the project and are on track to get things done on time.

If you tie your project management system into your git system, such as by putting issue-ids into your commit messages, it can also make it a lot easier to track down where bugs came from, as well as help future engineers understand why something was coded in the way it was.

Important Hard Skills

Hard skills deal more directly with code.

Code Standards

508 maintains a higher standard for code quality that some engineers might be used to. Luckily, maintaining good code standards is quite easy, and the requirements can be captured in a simple list:

  • Use a linter, and lint-on-commit (git hooks).
  • Have Github Actions, or similar, reject PRs that don't pass lint.
  • Ensure all new code is merged via PR, and only after code review.

All the issues around coding on a team, such as everyone using different editors, on different operating systems, with different opinions about code layout, are nullified with the enforced use of a linter. There's certainly room for conversation about what code style is decided on, but the important thing is that one style is decided upon, and enforced.

For more information on writing good code, I recommend the famous "The Pragmatic Programmer".

Git Standards

Git, or whatever version control is being used (obviously git, why are we even pretending that svn is relevant anymore?) should have enforced standards as well. Luckily, these are also simple enough to capture in a list:

  • Large code changes should be broken into as granular commits as possible.
  • Each commit should have a good, descriptive title, with more content in the message if necessary.
  • Where possible, indicate an issue number or ID that ties the commit back into the project management system.
  • Every new feature or bug fix should be a branch. Never commit directly to main.

Furthermore, git is a powerful tool, and 508 members are expected to have a relatively strong understanding of how to use git. If you don't feel confident in your git ability, make sure to ask other members, and read up a bit on some key git skills. For example, did you know that you can git add just one change in a file for one commit, and then git add other changes in the file for another commit? This can help you make granular commits. You can use tools like magit to help you do this, or whatever vscode ships with. At minimum, make sure to read up on the basics.

You should know how to do all of the following in git without needing to look it up or depend on Github's UI:

  • Clone a repository
  • Create and push a new feature branch
  • Update a branch even if it has local changes that the remote doesn't have, and the remote has changes the local doesn't have
  • Merge branches locally
  • Resolve a merge conflict
  • Change a commit message in history
  • Merge two or more commits into one commit
  • See git history for a given file
  • See general git history for project
  • Use git to see who the last engineer to change a given line was, and in what commit they changed it
  • Push code for someone else to see, then soft reset to continue working as if you never made that commit

Accessibility Standards

Accessibility is a core value of 508, and our commitment to web accessibility is actually the original inspiration of our name. When working on web projects, it's important to know about web accessibility. The best place to go to learn more is the folks over at w3.

Good accessibility isn't just ethical, it also leads to better SEO, improved click-through rates, and improved user happiness and engagement scores. For our web projects, good accessibility is non-negotiable!