From 7cd8149cc3cdf132ff355463d1d7434d86087611 Mon Sep 17 00:00:00 2001 From: Caleb Rogers Date: Tue, 9 Jan 2024 17:53:04 +0800 Subject: [PATCH] First draft done, need to index --- src/blog/index.html | 3 + src/blog/posts/good-engineering.html | 388 +++++++++++++++++++++++++++ 2 files changed, 391 insertions(+) create mode 100644 src/blog/posts/good-engineering.html diff --git a/src/blog/index.html b/src/blog/index.html index 7fc6932..a5efa8d 100644 --- a/src/blog/index.html +++ b/src/blog/index.html @@ -54,6 +54,9 @@

Posts

    +
  • + How to be a Good 508 Engineer +
  • New Project Setup Steps
    • diff --git a/src/blog/posts/good-engineering.html b/src/blog/posts/good-engineering.html new file mode 100644 index 0000000..75774ea --- /dev/null +++ b/src/blog/posts/good-engineering.html @@ -0,0 +1,388 @@ + + + + + + + + + + + + How to be a Good 508 Engineer + + +
    +

    + 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, 508.dev membership has exploded. We now have around 60 members, up from the 15 or so we had + before. Before, 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 question + 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. +

    +
      +
        + Stare at the code for a decent amount of time, no matter how unreadable it is. +
      +
        + 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. +
      +
        + 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. +
      +
        + Read any relevant documentation. If dealing with a library, looking at examples of their implementations. +
      +
        + Google the issue I'm having. +
      +
        + Stack overflow the issue I'm having. +
      +
        + Ask ChatGPT questions to help me define the problem better (ChatGPT solutions themselves are almost + never good and often are rabbit holes). +
      +
        + Go for a walk, then repeat all the above steps. +
      +
        + 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. +

    +
    +
    +

    + 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. +

    +
    +
    +

    + 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! +

    +
    +
    +
    + + +