DEV Community: Josh Buckland

Brag about it: Writing a brag doc

Josh Buckland — Thu, 19 Aug 2021 10:20:44 +0000

You can find a Brag Doc template file in this Github repo.

This is based on a blog post by Julia Evans that is well worth a read in addition to what is written here.

What the heck is a "brag doc"?

A Brag Doc is a document you use to keep track of all your work that you do
throughout the quarter/year/period so that you can look back on it at the end when doing reflective work and asking for feedback. As mentioned in the blog post linked to above

There’s this idea that, if you do great work at your job, people will (or should!) automatically recognize that work and reward you for it with promotions/increased pay. In practice, it’s often more complicated than that – some kinds of important work are more visible/memorable than others. It’s frustrating to have done something really important and later realize that you didn’t get rewarded for it just because the people making the decision didn’t understand or remember what you did.

Being recognised for your work though isn't just about promotions or getting raises (though these things are both still important). This document can also help you reflect on what you learn and work on, the things that are important to you, or where you'd like to go next.

But why should I bother?

Let's start by considering some of the more specific reason for why it's worth making a brag doc, and this should then help us understand what we want to put in it.

You won't remember everything you did

You're going to be doing so much in your job, both big and small, that remembering all of it is going to be difficult, if not impossible. Maybe you can go through a bunch of pull requests on Github. But what if you were pairing on a piece of work? If you're lucky you'll have remembered to use co-authored-by commits to try and keep track of that work, but that won't necessarily help with the Pull Requests or with work that isn't coding. Maybe you'll rely on Trello boards or similar to capture that work but, again, there will be so many times where some one-off mentoring or code reviewing would go uncaptured that you'll fail to capture all the really important "other work" that you do.

Instead, try make a habit of writing down all that work in your brag doc at the end of the day/week. There are some great ways to build this into your routine that I'll discuss below, but one of the key features of a brag doc is its function in ccapturing all of the work you do. So try remember to stick it all in there!

Your manager won't remember everything you did

This is basically a repeated of the previous, but with some added caveats. There's a good chance that your line manager won't necessarily be on the same team as you. Maybe you'll mention to them in your 1:1 sessions some of the work you did, but without a written record they probably won't remember it all. Working with your manager is one of the best ways to fat track your career and your development, so making sure that they have an up to date reference of everything you've been doing is a great way to facilitate this.

Remember to share it with your manager!

your colleagues won't remember everything you did

See above. (Feedback from colleagues is a key part of your development. Help them out and do yourself a favour at the same time by sharing your doc with them when it comes to feedback time.)

Writing your brag doc

At its simplest, your doc is just a list of your accomplishments over the course of your time in the job. So stick everything you do and everything you're remotely proud of in it./ Presentations, focus group work, documentation, mentoring, code review. Anything and everything should go in here. This might be enough for you but if you want to get the most out of it it's worth doing a bit more than that.

Build a bigger picture. What are you focussing on currently? Maybe you're wanting to build out your understanding of client-side development and have focussed on work around that. Or maybe you've tried really hard to tackle accessibility or internal process, so there's more conceptual work happened recently. By giving a general idea of what you're aiming for it helps you and anyone else reading the document to understand why you've highlighted or expanded on some work over others.

Try to notice patterns as you update your document. What kind of things are you most proud of? What do you wish featured more in your day-to-day work? What projects had the effect you wanted? What didn't work even if you're proud of it? All these question can really help with breaking down that bigger picture and with fleshing out the individual sections.

Finally, and arguably most importantly, don't forget the fuzzy work!

What is "fuzzy work"? Fuzzy work is a lot of the work that you do that feels harder to quantify. It's the kind of stuff that doesn't always feature on a Trello card or that falls outside of your team's current weekly focus.

This can include stuff like:

Improving code quality or making code reviews a bit easier by establishing some guidelines around coding style.
Mentoring work. - Doing code reviews for your team and others.
Writing documentation! Everyone forgets how important this is because it doesn't produce a fancy product at the end, but it's really important.
Getting rid of a bit of tech debt without it being part of a health week/healthcard.
Design docs. Spending a few days sketching out your future work is really important and will help the team and anyone else you work with to understand what you're aiming for.

As Julia Evans says in the original blog post:

One way to approach this is to, for each goal:

explain your goal for the work (why do you think it’s important to refactor X piece of code?)

list some things you’ve done towards that goal

list any effects you’ve seen of the work, even if they’re a little indirect

If you tell your coworkers this kind of work is important to you and tell them what you’ve been doing, maybe they can also give you ideas about how to
do it more effectively or make the effects of that work more obvious!

Where should I start?

Wherever you like! I'd recommend something digital because it's easier to share, but after that it's really up to you. A Google doc is a good way to share it but keep it semi-private. You could also just stick it in a Git repo. It might be quite scary to make it (potentially) so public but, as long as none of the work is confidential, you should be proud of it and it can really help if you ever decide to move on from your current place of work and need evidence for interviews.

There are also some really fun ways of making this collabroative and supporting your co-workers. Start a regular brag session where you and a few others get together to update your brag docs and hype each other up. It can be a really nice morale boost to be reminded of and praised for a piece of work you'd forgotten all about. These are particularly useful around performance review time when having someone to bounce off and work with can make the process of self-reflection much less intimidating.

Structure

Below lifted directly from the blog post by Julia Evans.

Goals for this year:

List your major goals here! Sharing your goals with your manager & coworkers is really nice because it helps them see how they can support you in accomplishing those goals!

Goals for next year

If it’s getting towards the end of the year, maybe start writing down what you think your goals for next year might be.

Projects

For each one, go through:

What your contributions were (did you come up with the design? Which components did you build? Was there some useful insight like “wait, we can cut scope and do what we want by doing way less work” that you came up with?)
The impact of the project – who was it for? Are there numbers you can attach to it? (saved X dollars? shipped new feature that has helped sell Y big deals? Improved performance by X%? Used by X internal users every day?). Did it support some important non-numeric company goal (required to pass an audit? helped retain an important user?) Remember: don’t forget to explain what the results of you work actually were! It’s often important to go back a few months later and fill in what actually happened after you launched the project.

Collaboration & mentorship Examples of things in this category:

Helping others in an area you’re an expert in (like “other engineers regularly ask me for one-off help solving weird bugs in their CSS” or “quoting from the C standard at just the right moment”)
Helping new team members get started - Writing really clear emails/meeting notes - Foundational code that other people built on top of - Improving monitoring/dashboards/on call - Any code review that you spent a particularly long time on/that you think was especially important
Important questions you answered (“helped Risha from OTHER_TEAM with a lot of questions related to Y”) - Mentoring someone on a project (“gave Ben advice from time to time on leading his first big project”) - Giving an internal talk or workshop

Design & documentation List design docs & documentation that you worked on:

Design docs: I usually just say “wrote design for X” or “reviewed design for X”
Documentation: maybe briefly explain the goal behind this documentation (for example “we were getting a lot of questions about X, so I documented it and now we can answer the questions more quickly”)

Company building

This means “things you did to help the company overall, not just your project/team”. Some things that go in here:

Going above & beyond with interviewing or recruiting (doing campus recruiting, etc.)
Improving important processes, like the interview process or writing better onboarding materials
Working groups e.g. diversity, hiring etc.

What you learned

Try listing important things you learned or skills you’ve acquired recently (bonus points if you did a write up on it after)! Some examples of skills you might be learning or improving:

How to do performance analysis & make code run faster
Internals of an important piece of software (like the JVM or Postgres or Linux)
How to use a library (like React)
How to use an important tool (like the command line or Firefox dev tools)
About a specific area of programming (like localization or timezones)
A new area like product management/UX design/software engineering
How to write a clear design doc
A new programming language

It’s really easy to lose track of what skills you’re learning, and usually when I reflect on this I realize I learned a lot more than I thought and also notice things that I’m not learning that I wish I was.

Outside of work

It’s also often useful to track accomplishments outside of work, like:

blog posts
Talks/panels - Open source work - Industry recognition I think this can be a nice way to highlight how you’re thinking about your career outside of strictly what you’re doing at work. These things are not compulsory though and you shouldn't feel pressured to do more than your day-to-day work.

Learning Go by making a Todo List app [Part 1]

Josh Buckland — Sun, 09 Aug 2020 16:40:31 +0000

Hello and welcome to my journey on becoming a Golang developer. I'll be doing this by creating the now-overused Todo List app. To try and learn as much about Go in the process, I want to handle as much of the logic in Go as possible, including parsing the form request from the web page.

To make this happen I'll be using the resources listed below, as well as lots of googling.

Let's start though by defining what we want from our Todo List app by defining a number of user stories.

User Stories

As a user I want:

To add items to and remove items from my todo list using a web interface and form.
To add items for either myself or a team I belong to. There will be multiples of either.
For my personal items to be hidden from the team I belong to.
For my todo list to persist between sessions.
To be able to set an optional due date for an item.

Using Go

We'll start by making a file to put all of the code in

touch main.go

and then add in a few basic requirements for starting out.

package main

import (
  "fmt"
)

func main() {
  fmt.Println("Hello from your new todo list app")
}

We then build the program using

go build github.com/buck06191/todo-app

before running the binary that this creates:

Reading from the command line

Let's get started on the Todo List app by starting as simple as possible. I'll begin by making a CLI for the ToDo list in Go. Ideally a lot of the logic used to make the CLI work will transfer over to handling requests from the web page interface that will come later. The command line needs to accept a JSON string of the form

{
  "task": "todo task",
  "due": "optional due date (yyyy-mm-dd)"
}

This should then be given a unique ID by Golang or the database. For example,

{
  "id": 1,
  "task": "Practice Go",
  "due": "2020-02-02"
}

Let's start by reading that in and echoing it back to the user on the CLI.

We begin by using the flag package to set up command line flags and read in values.

We then need to make a function to read this value and print it back out to the terminal. The flag.String function gives us an address to the value, meaning we'll need to access it as a pointer.

Finally we add in a main() function that parses the arguments using flag.Parse() and then echoes back the item.

// Package todo contains a basic CLI todo app
package todo

import (
  "flag"
  "fmt"
)

var todoItem = flag.String("add", "Something worth doing", "Item to add to todo list.\n\t{\"todo\": task to do, \"due\": date due (YYYY-MM-DD)}")


// EchoItem echoes back the command line input.
func PrettyPrintItem(item *string) {
  fmt.Printf("You entered:\n\t%s", *todoItem)
}

func main() {
  flag.Parse()

  PrettyPrintItem(todoItem)
}

This should give the following:

However, we need to make sure that we parse the command line input to check for anything that doesn't fit our desired JSON structure. We need to deserialise our JSON into a struct and then parse it in order to convert it into a usable format.

First, we need to define our TodoItem type which we can then parse as required.

import (
  ...
    "encoding/json"
)

// TodoItem is the internal type used to store the JSON data that is
// deserialised by the app.
type TodoItem struct {
  Todo string `json:"todo"`
  Due  string `json:"due,omitempty"`
}

Here we have used struct tags to define the json field names, as well as allowing for an empty Due field. Next we need to define a type for our ParsedTodoItem where we convert the Due field to use the time.Time type.

// ParsedTodoItem is the same as the TodoItem type, albeit with the `Due` field
// parsed to due the `time.Time` struct.
type ParsedTodoItem struct {
  Todo string
  Due  time.Time
}

We then parse our command line input with the end goal of producing a ParsedTodoItem. First, we deserialise the string from the command line using json.Unmarshal, giving us a TodoItem. Next we take the Due field of this deserialised JSON and parse it to a time.Time using the parseDueDate function.

If the field is empty, we return a zero-value for the time.Time type. Otherwise, we then check if we can parse it from our correct format. Go uses a particular way of defining a datetime string format, as described in the time.format docs. If the format is incorrect, we tell the user and exit the program. Moving forwards we'll want to handle this more gracefully, but for now (when only handling single tasks from the command line), this works fine. If the passed date can be parsed, it is returned from the function.

Finally, we build our ParsedTodoItem from our original Todo and our new parsedDueDate and return that from this function. I've purposefully chosen to build a new variable here as I'm trying to avoid side effects that could potentially come from mutating the value in place.

func parseDuedate(dueDate string) (parseddueDate time.Time) {
  if dueDate == "" {
    return time.Time{}
  }

  const dueDataFormat = "2006-01-02"

  parsedDueDate, parseErr := time.Parse(dueDataFormat, dueDate)

  if parseErr != nil {
    log.Fatal("Badly formed due date.")
  }

  return parsedDueDate
}

// ParseInput parses the input into something more usable.
// This includes checking for empty input and parsing the
// `due` field.
func ParseInput(input *string) ParsedTodoItem {
  var todoItem TodoItem

  err := json.Unmarshal([]byte(*input), &todoItem)
  if err != nil {
    log.Fatal("Invalid JSON passed to ./todo-app")
  }

  parsedDueDate := parseDuedate(todoItem.Due)

  parsedItem := ParsedTodoItem{Todo: todoItem.Todo, Due: parsedDueDate}

  return parsedItem

}

We now need to modify our PrettyPrintItem function to take this new type. First we convert the struct back to a JSON string, and we use json.MarshalIndent to format the output into something slightly easier to read.

// PrettyPrintItem echoes back the parsed command line input.
func PrettyPrintItem(item ParsedTodoItem) (n int, err error) {
  formattedItem, err := json.MarshalIndent(item, "\t", "\t")
  if err != nil {
    return 0, err
  }
  return fmt.Printf("You entered:\n\n\t%s", string(formattedItem))
}

Compiling and running this final code with a number of example JSON strings gives us the following:

In the next part we'll look at introducing testing into the codebase so that we don't need to continually run against command line examples in order to check that the code is working. (Ideally I'd have done this from the start and followed test-driven development ideals.)

What are some examples of less obvious web development features/technologies worth learning?

Josh Buckland — Mon, 03 Aug 2020 10:44:20 +0000

I've been working as a bona fide junior developer for almost 6 months now and I've got a reasonably good handle on the foundations of web dev stuff and know the big obvious things to learn.

But what are some useful but maybe lesser-known technologies worth looking into? One example I saw would be WebSockets which I only really noticed after seeing them in an interview task example. Another would be looking deeper into ES Modules and trying to understand how they actually work.

Love to hear what you think and recommend!

Automating my WSL Setup

Josh Buckland — Fri, 31 Jan 2020 16:53:57 +0000

Setting up WSL

A few months ago I got rid of my old laptop that I had dual booted Linux and Windows on and decided to get something much smaller and much more portable. I managed to find an ex-display 13" HP laptop and hey-ho, my portability increased ten-fold.

However

This tiny-but-mighty bargain has nowhere near enough hard drive space for me to dual boot Linux and I'm too far down the Unix path to even attempt relearning my workflow on Windows.

In walks WSL to save the day

There are so many blog posts about WSL that are based on a way deeper understanding than I have, but the general idea is that it's a Linux OS inside Windows 10 and it means I don't have to dual boot.

Over the last few months I've used WSL in its various incarnations on both my tiny laptop and my desktop PC, using different terminals, settings, configurations etc. And every time I have to reinstall it or just want a clean slate to work from, I have to try and remember everything I did last time I set it all up.

This is a massive waste of time and I always end up forgetting what I did. I've also stumbled across loads of little bugs, the most recent being that the excellent spaceship prompt that I happily use on my work Mac does not get on well with WSL. For whatever reason (probably already documented read/write speed issues) changing directory would take upwards of 7 seconds.

In an attempt to fix this I ended up reinstalling WSL from scratch and loading in different configurations until I found a solution that worked. But setting this all up on two different computers was a massive pain and I really don't want to have to do this again.

The answer

Automation.

Kind of.

I decided to hack together a script that basically automated all the steps I had to take after installing Ubuntu 18 on WSL.

The resulting script and config can be found in a github repo along with instructions on how to run it all and the end result can be seen below:

I decided to use powerlevel10k as it gave me enough functionality without slowing the whole thing down. I'm also using Windows terminal with the FuraCode Mono Nerd Font as I found these gave me the best experience in terms of nice Powerline symbols and readability.

Inevitable Problems/Bugs

I did have a few problems that I would love someone to solve for me. The main one is that I install zsh inside the script, followed by oh-my-zsh. After this step oh-my-zsh kicks me back out to prompt, requiring me to then run the script again where it can then skip to the following steps and then run through to completion.

It's not a deal breaker but it is annoying.

I hope that if anyone else is using WSL and is needing a responsive and easy to run set up that this can help them.

If you find anything that can be improved or needs fixing, please do raise an issue on Github and I'll give it a look when I get chance.

You can follow me on Twitter at @itsJoshB for occasional ramblings about tech and other things.

Thanks for reading!

You Got This 2020

Josh Buckland — Mon, 20 Jan 2020 18:51:31 +0000

I've just got back from what must be one of the best tech conferences going, and what makes it so special is that it isn't even really about tech. YouGotThis is an annual, single-stream, "tech" conference which focusses on the oft-forgotten "core skills" that are key to working in tech in a way that is both healthy and productive. It's aimed at early career developers, be those junior devs or people that are still looking for that first role, but I actually think that much more senior developers and managers could really benefit from attending. In fact, I think that a lot of what was covered in the talks is relevant far outside of tech specific roles and everyone could benefit from attending!

The Event

Photo: Venues of Excellence

This year the conference took place in Birmingham at Millennium Point. It was really great to see a conference like this take place outside of London, shining a light on the tech world outside of Silicon Roundabout. Underland, who organised the event, did a fantastic job at making the event truly accessible. The toilets inside the event area were all gender neutral, with typical toilet facilities available elsewhere in the venue, and attendees all wore name badges with a pronouns field. All of the food was vegan and the event was a dry event. They also offered a couple of schemes to widen the event up to under represented groups. Ticket scholarships were offered for these groups which included, but wasn't limited to:

LGBTQIA+ people, people of colour, women, non-binary people, and those with disabilities.

This was funded in part by other attendees buying an extra ticket alongside their own which could then be used in this scholarship scheme. Underland also offered full scholarships which covered travel and accommodation alongside the ticket cost.

These little touches do a great job of making the event far more accessible to people who might otherwise feel excluded. All of the information about their inclusion work for the event can be found at https://2020.yougotthis.io/inclusion

Topics

Photo: Underland Events

There were 9 separate talks on at the event:

It's not your job to love your job - Keziyah Lewis @KeziyahL
Learning to invest in your future - Matthew Gilliard @MaximumGilliard
How to find your perfect mentor - Amina Adewusi @a_adewusi
So good they can't ignore you! - Gargi Sharma
Level up: Developing developers - Melinda Seckington @mseckington
Making your first days count - Nathaniel Okenwa @chatterboxCoder
Company culture, performance reviews and you - Ruth Lee @yoursruthlessly
Unions got this: Organising the tech trade - Dan Parkes
Real talk about when to walk away - Amy Dickens @RedRoxProjects

I'm not going to write up all of these talks word for word, because that feels a lot like plagiarism and I honestly couldn't do them justice. What I would like to do though is summarise the key themes that I found across all the talks.

Your needs ≠ your workplace's needs

Now, this one isn't always true, especially if you're a freelance developer that works for themselves. But for a lot of developers, we're working for companies that want to sell themselves to their employees, investors and customers are being revolutionary, game changing forces for good. The reality though is that we live in a capitalist world and the company doesn't care about you. Your manager might care about you. Your colleagues might care. Even the CEO might care. But the company is an entity whose sole purpose is to maximise its own value above all else. Keziyah Lewis, Ruth Lee and Amy Dickens all covered this in great detail.

This isn't to say that your company is your enemy. What it does mean though is that you need to make sure to look after yourself, because the company won't do it for you. For example, a performance review is not a ground truth, objective analysis of your skills. What it is, is a way for your colleagues, managers and other associates to provide feedback that then assesses how you fit the company's culture. A well established company or team will have different values and a different culture to something like a start up. Remembering this is the best way to make sure you're both in the right role and company for you, and to properly assess how your strengths suit the needs of that role/company.

Build a personal brand

So it should be noted that I'm both British and introverted, so things like "building a personal brand" trigger some sort of deep rooted suspicion inside me, and before attending YouGotThis I'd probably have listened to it. But so many people mentioned it and extolled its virtues that I think I need to give it a second chance.

For me, building a personal brand seems to be about establishing and defining who you are. Your values, your goals, your needs. It's only after you've started to sketch these things out that you can really start to put in the time required to make sure you're both being your best and getting the best out of your job. Once you've started to work on this you can find the right company to work for, find your working style, figure out the best way to learn, make sure you're being recognised for the work you do, and then so much more. It helps you in planning for the future, assessing the present and reflecting on the past.

Make a Brag Doc

I had never heard of a brag doc before attending this conference, but following Gargi Sharma's talk where she mentioned it, almost every speaker afterwards brought it up. There's a really great blog post about building a brag doc by Julia Evans that Gargi mentioned. I'll leave that here (https://jvns.ca/blog/brag-documents/) instead of writing it all out again and you should definitely give it a read.

By building a brag doc, you're highlighting your skills and your work. There are all sorts of tasks that you do every day, big and small, that might go unrecognised unless you point them out and brag about them. Also, you won't remember everything you did in the last week/month/quarter unless you make a note of them. Maybe put together some important documentation or made a small improvement to the codebase that fixed a security hole. Write it down, share it with your manager and your colleagues that give you feedback. They're just as human as you and they're bound to forget most of the work you've done recently. All you're doing by sharing your doc is reminding them of the things you so that they can be reminded of how awesome you are!

Work with your manager

Your manager is there to help support you in your journey as a developer. A great example of this is from Melinda Seckington's talk about how your engineering manager can help you to develop by using ideas from game design. Right the way from starting a new game (joining the company) through to leveling up (developing your skills), your manager is in a great position to help you out through fast and constructive feedback and providing plenty of opportunities for you to develop your skills.

Nathaniel Okenwa's talk about settling into a new role and then accelerating your growth highlighted building a productive working relationship with your manager as a key component of the first of three phases in starting a new role. (The three phases he focused on were Observe, Understand and Create).

So with all that in mind take some time to build a good relationship with your manager. They're not just there to tell you what to do.

Be part of the community

Maybe this comes in part from being at a conference, but there was definitely a running background theme across the talks about being involved in the tech community. Whether it was Amina Adewusi's talk about the benefits of finding and being a mentor, Matthew Gilliard's advice to use social learning as a way to improve, or Gargi's tips for networking as an introvert by writing a blog or leveraging one on one conversations to build connection, being part of the tech community is a great way to "level up" as a developer.

This blog is actually my first step towards doing this. I'm hoping that by writing this blog, I can build up my network and contribute towards the tech community. With that in mind, I'll be posting in the next few weeks about other steps I want to take towards giving back to the community and being part of it.

You are more than your job!

One of the most important things to come out of this conference was about respecting yourself and your needs. You need to make sure that whatever you do in your job, you're doing it for you as well as your company, and that you're maintaining a healthy work/life balance. The value that you gain from this benefits you and them.

And the best way to do this is to implement some of the ideas above. Figure out who you are, build a brag doc to highlight your strengths and the work you do, work with your manager to develop yourself and be part of the community.

I'm going to follow up this blog post with some of the specific things I'm going to be doing in 2020 to try and follow through on what I've learnt.

I'm also going to (eventually) get this up on my own blog. So when that happens I'll keep you posted about it :)

Thanks,

Josh