Skip to main content

3 posts tagged with "sprouts"

View All Tags

ยท One min read

This is my digital garden! I've organized the content by tags:

seeds - These are notes and half-baked thoughts.

sprouts - These are blog and talk drafts, or more rambling trains of thought that still have structure.

trees - These are fully fledged blog posts, or even essays!

There are other tags, too of course, but those will have to do with topics and less to do with the content's position in my garden.

Hope you enjoy clicking around. ๐ŸŒฑ

ยท 4 min read

Writing A Clear Code Exampleโ€‹

If you're a developer advocate, you've probably written a code example or two. The purpose of writing a code example is completely different from the purpose of writing production code. "It's messy, but it works," doesn't fly. It has to work and teach other developers. At the same time, you might not show the extension of an app to the fullest degree, for modularity's sake. In my time at a small startup, I've lost count of the number of code examples I've created. I've made some mistakes and learned a few things along the way. Here are some lessons that I can share with you.

Keep the Visual Impact In Mindโ€‹

Keep it clean-looking. Running prettier before pushing is important, but that's not the only thing to consider here. Say I were writing a sample to show how to retrieve information from a certain API. How can I improve the readability of this codeblock?

fetch('https://api.sample.com/v3/endpoint',
method: 'POST',
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
Authorization: 'KEY'
},
body: JSON.stringify({ body: 'data' }),)
.then((response) => response.json())
.then((response) => console.log(response))
.catch((err) => console.error(err))

Well, I could pull out headers and options, make them variables, and pass them into the fetch call.

const headers = {
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
Authorization: 'KEY',
},
}

const options = {
method: 'POST',
headers: headers,
body: JSON.stringify({ body: 'data' }),
}

fetch(
'https://api.sample.com/v3/endpoint',
options
.then((response) => response.json())
.then((response) => console.log(response))
.catch((err) => console.error(err))
)

As you can see, that makes it a lot easier to see what options you need to pass to the API endpoint to receive a response.

Comment Wiselyโ€‹

Let's say I was working on the same block of code. Even though this is a code sample, it shouldn't be necessary to comment on a lot of lines.

// these are the headers to be sent in the request
const headers = {
headers: {
// default is application/json
Accept: 'application/json',
//content-type is application/json
'Content-Type': 'application/json',
// send authorization from your account here
Authorization: 'KEY',
},
}

The comments are starting to make this hard to read and I haven't even gotten to the options variable yet.

If you know your audience well enough, you might know that they're familiar with sending headers to an API. I'm a fan of short documentation links in templates, just in case:

// https://www.linktoapidocumentation.com
const headers = {
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
Authorization: 'KEY',
},
}

Otherwise, I try to keep comments out of the template, unless I'm doing something that interrupts a well-known coding paradigm.

Know The Limits Of Your Sampleโ€‹

It's important to keep your sample clear by illustrating one concept at a time (unless, say, it's a sample for a livestream and you want to show multiple aspects of your product, then-- time to go all out!).

This modularity is something that I have seen clearly illustrated in Next.js sample code. In Next.js's form example, you can see on line 34 that the information on a form is displayed in an alert.

Now, an alert box is often considered bad form (haha) in production. However, the authors of this code sample have wisely used it as a way to keep the modularity of their sample repository intact. Sure, they could have gone on and shown how to use useRouter() and query params to pass this information on to a new page, but they decided to focus on showing how to use forms in Next.js, so they ended the functionality on this page with an alert box.

In Conclusionโ€‹

What have we learned? Well, the style of your code sample is determined by your scope and audience. Whether or not you need to comment to explain your code depends on your audience's understanding of the general concepts you're illustrating an instance of. Also, how much functionality you highlight depends on whether you're writing an example for documentation or a codebase to walk through a livestream. No matter what though, keep your code neatly formatted and organized. The need for clarity never changes. ๐Ÿ˜‰

ยท 3 min read

I started bootcamp when my daughter 2 months old. Yes, it was tough. But it also helped me understand what I wanted from a tech career. These two aspects of life -- tech and parenting -- don't have to be in tension. Here are some of the ways I've adapted to being present for other developers as a developer advocate, while being present for my daughter.

Boundariesโ€‹

The biggest thing is having a hard line on what you will and will not accept from work.

These hard lines can revolve around:

  • How many hours/week you work.
  • How much you travel for work.
  • Whether there is parental leave.
  • How much pay you receive.
  • Whether you will work remote.

I actually found that this made it easier, not harder, to narrow down opportunities. If you eliminate some of them because they won't work with your lifestyle, you have a filter by which to figure out which jobs you're really interested in.

Attitudeโ€‹

The other big thing to remember is that parenting is not limiting. Yes, you won't make the same choices as you did before. But you will make choices based on a new aspect of your life that will enrich it.

And, it's ok to make choices based simply on what you want. There's a lot of pressure on parents to do the "right" thing, but the most important thing is to take care of yourself so you can be there for your kid.

'What aligns with my joy?' vs 'What do others think I should do?'โ€‹

It will free up a lot of work/life tension if that's the first question you ask yourself -- what aligns with my joy?

There's a lot of pressure on developers and parents to behave in very particular ways. You don't have to participate in what doesn't suit you.

If your joy is found in a life pattern that's not attainable yet, you can make small daily changes to work towards your goal. If there's another tech subfield you want to work in, make a goal to talk to one person in that field per week. If you want to have a job that's more flexible and allows you to pick up your kid from school early, apply to one of those jobs a week.

We all know that a life that aligns with your inner peace is not necessarily easy. There's a lot of external turmoil in the world. It can be exhausting, scary, and downright overwhelming to be a parent, especially a new parent, in tech. But it's a lot easier when you pay attention to what you, as a whole person, delight in.

Caveatโ€‹

There are a lot of systemic issues out there that make life difficult for caregivers. This post is not intended to say you can solve all those difficulties with an attitude adjustment. Laws and cultural expectations need changing. This post is solely intended to help with any internal friction you may be experiencing, since these thoughts have helped me.