5 posts tagged with "sprouts"

Over my career I've had to learn new things many, many times. I've been an elementary school teacher, a digital marketer, a software engineer, and now I'm a full-time developer advocate. Over and over again, I've had to learn completely new concepts. It's great; it keeps me humble, it keeps me happy. There's a lot of dopamine involved in learning. But one of the most difficult parts of learning is knowing what you don't know. And knowing what you don't know is important, because it keeps you from making the types of mistakes that emanate from errors in judgment.

I've learned a couple of things about defining the limits of my knowledge about a concept. I'm sharing my framework here in case it's helpful to anyone else in tech.

Stage 1: Nothing​

The first stage of getting to know a new concept is the easiest to define. I'm starting from nothing!

This is great. I know exactly what I don't know. Let's say I'm completely brand-spanking new to the concept of an API. Here is a diagram of what I don't know about APIs:

It doesn't get more accurate than that. I'm not kidding. "What you don't know" will surprise you again, and again, and again. The framework I'm suggesting here will not save you from being wrong in front of people. But I think it will give you some general guidance on how to approach learning new things.

Stage 2: One Instance of a Concept​

So let's consider universal concepts. Definitions that we all agree on. For example, an API according to Wikipedia is

"An application programming interface (API) is a way for two or more computer programs to communicate with each other."

Maybe that's not the most complete definition, but I think most techies would agree on what's there. Now, you can memorize this definition, but you won't have experiential knowledge of an API until you've met one out in the wild.

Let's say I'm at that stage. I'm getting used to querying a REST API, and I'm learning to build one myself with Python or Node Express or something. This definition applies to the REST API I'm building, so I'm gaining experience with one type of API. One particular instance of this universal concept. Here is another map of my brain:

So, I'm learning something about REST APIs. And that's it for now. The arrow is pointing to a boundary that I'm not aware of:

I don't know what's common to REST APIs and all APIs, and what's different.

So, I've seen one particular instance, but I've not seen another instance of an API. And this is a problem because there are different kinds of APIs underneath the universal concept of "API". Like there are different kinds, or species, of cats underneath the "cat" genus. And tigers are very different from lions.

Stage 3: Two instances, of different kinds, of a concept.​

Say I start implementing not a REST API, but a GraphQL API. It's a different kind of API from a REST API, like lions are a different kind of cat from tigers. My worldview on APIs begins to break down. It's destroyed by differences between REST APIs and GraphQL APIs, like

• GraphQL is an application layer, while REST is a style of API. Not every API is in the REST style!
• GraphQL requests are JSONesque, while REST requests are often parameterized in URLs. Not every API uses parameters the same way! Or has the same request format.
• You define GraphQL with a schema, rather than a list of endpoints. Not every API is defined the same way!

I know that diagram just got complicated, I'm sorry. But this is the most important stage to take notes at. Why? Because when you realize what assumptions you've made, you realize what questions to ask the next time you encounter a new kind of API.

These are the assumptions I've made:

• All APIs are in the same style.
• All API requests are formatted alike.
• You define APIs in the same way.

Now that those assumptions have been broken by my experience, I know what questions to ask next time I'm learning a new kind of API.

Stage 4: The third instance of a different kind.​

Ok, say I'm learning what a tRPC API is in order to implement on at work or something. Based on the kinds of assumptions I made last time, what might I ask now?

• How does the style of tRPC compare to REST and GraphQL, the ones I'm familiar with?
• How are tRPC requests formatted?
• How do I map or define a tRPC API?

These questions will help me understand what a tRPC API is much faster than I understood what a REST or GraphQL API is.

Furthermore, I'll be understanding the general concept of an API even better, because I'll be understanding what is in common between all these kinds of APIs. I'll also be understanding GraphQL and REST APIs better at this stage, because I can then make lists of their limitations.

Generalizing this process​

I think every time you learn something new, you have to go through these 4 stages and there's not really a way around that.

But if you do it consciously, it speeds up the process of learning.

So when you're beginning, acknowledging "I know nothing about this. I should ask someone who knows something about this what is the best instance to build first," can save you some pain.

Then again, once you've built your first instance, acknowledging "I might be making assumptions here that don't apply to other instances. I should ask someone who has built other kinds of instances what the differences are," will help you make decisions about whether to learn a new paradigm when you're building your next instance.

Recently I've joined the developer advocate team at Confluent, which is full of highly experienced speakers who have mentored me as I craft abstracts.

I'll be honest; when I began writing abstracts I thought, "How hard can this be? I've written plenty of blog posts, technical articles, and the occasional haiku. Abstracts will come naturally."

Reader, they did not! The art of writing and fine-tuning abstracts is challenging, but learn-able. Luckily, I've gained a lot of knowledge from my teammates and now I feel a lot more comfortable with writing abstracts. I wrote this post to hand on a few of the things I've learned.

1. Connect with your audience in the first sentence.​

Let's start with this abstract that I've written up for the purpose of this blog post:

"Come to my talk about choosing React frameworks. We'll learn how and why to choose the framework that suits your web development needs. You'll learn criteria for choosing a web development framework and how to apply them. By the end of my talk, you'll know more about the React ecosystem and have the tools to get the job done."

The first sentence, "Come to my talk about choosing React frameworks," is a nice invitation but it doesn't really hook the reader. In order to connect with the audience, it's a good idea to start by mentioning their pain point. In this example, a good first few sentences might be more like the following:

"The number of React frameworks in recent years has reached an overwhelming height. Social media debates run fierce. There's only one consensus: choosing the right framework for the job is of paramount importance. But how, exactly, do we pick a framework?"

2. Position your pronouns thoughtfully.​

Take a look at the abstract once more.

"The number of React frameworks in recent years has reached an overwhelming height. Social media debates run fierce. There's only one consensus: choosing the right framework for the job is of paramount importance. But how, exactly, do we pick a framework? We'll learn how and why to choose the framework that suits your web development needs. You'll learn criteria for choosing a web development framework and how to apply them. By the end of my talk, you'll know more about the React ecosystem and have the tools to get the job done."

There's "we", "you", and "my" here. Consistency is key in all writing, but for talks, you might choose "we" over other options to reflect a sense of comraderie with the audience.

3. Let your solution for the audience's pain point be clear.​

Currently, the solution that the speaker offers is vague:

"We'll learn how and why to choose the framework that suits your web development needs. We'll learn criteria for choosing a web development framework and how to apply them. By the end of the talk, we'll know more about the React ecosystem and have the tools to get the job done."

In fact, all you can really tell is that the speaker is offering some kind of solution. There are no hints as to what it might be.

Here's a better way to express the speaker's intention:

"We'll distill the criteria for selecting a React framework into three crucial questions. Then, we'll walk through a few use cases together to garner some experience making these decisions. What does the decision making process look like for building static portfolio sites, large e-commerce sites, and mobile game apps? By the end, we'll feel ready to critically appraise React frameworks, familiar or unfamiliar, for our own projects."

This gives some detail ("three crucial questions", and the use cases) without giving everything away. It also communicates the value to the audience: a confidence in their choice of framework.

Now the whole abstract reads:

"The number of React frameworks in recent years has reached an overwhelming height. Social media debates run fierce. There's only one consensus: choosing the right framework for the job is of paramount importance. But how, exactly, do we pick a framework?

We'll distill the criteria for selecting a React framework into three fundamental questions. Then, we'll walk through a few real-life use cases together to garner some experience making these decisions. What does the decision making process look like for building static portfolio sites, large e-commerce sites, and mobile game apps?

By the end, we'll feel ready to critically appraise React frameworks, familiar or unfamiliar, for our own projects."

I think this version sounds a lot more interesting and clear, don't you?

This is my blog! 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. 🌱

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

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.