Skip to main content

2 posts tagged with "developer advocacy"

View All Tags

· 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

Using Visual Thinking to Teach

How would you teach someone to draw a house? What would you say? I might write something like this.

"Draw a horizontal line. Draw two lines of the same length, starting from the ends of the original line, and perpendicular to the original line. Connect the two lines with another straight line. Now you have a square. From the top corner of your square, draw a line at roughly 45 degrees to the top line of the square..."

Whew. That's already a mouthful, and we haven't even finished the roof yet.

Ed Emberly was an artist who taught children how to draw. If he were to teach a child to draw a house, he would draw something like this (this is my own drawing):

Three slides. The first shows a square. The second shows a triangle on top of the square. The third shows a rectangle added to represent a door. There are mini version of each shape under each step.

Without a single word, you understand how to draw a house in a moment or two.

This is power of visual thinking. It's important in all fields of teaching. In developer advocacy, it can be used to teach audiences with graphs and maps and videos (of course, audio must also be supplied). Visual thinking can also help developer advocates create the constraints they need to be creative. I think this is the less obvious point, so let's talk about it.

Using Visual Thinking to Plan Projects

Let's say I were a developer advocate who was planning a tutorial to introduce developers to a new SDK (Software Development Kit). Say that this SDK provides the developer with a type of hyperaccurate timestamp. To show the purpose of the SDK, I use it in the framework that I used to build this website, docusaurus.io. I'm also really excited about the docusaurus CLI (Command Line Interface), so I'll describe how to use that to view the pages in development. I'll draw a map of what I'm doing.

Three stacked blocks representing steps, only one with SDK mentioned

Hm. That's a lot of real estate devoted to docusaurus. Only one step is devoted to the SDK I'm writing a tutorial about. Maybe this plan could work for a livestream format, but for a tutorial, I'd better narrow my focus:

Two stacked blocks representing steps, one with SDK mentioned

There. I've planned my tutorial and given it a good focus, using visual thinking!

Where To Go From Here

I hope this has given you some good ideas about how to use visual thinking in your own approach to developer advocacy. It's helped me, in that it's given me some 'shortcuts' to project planning and also helped me communicate concepts more clearly to my audiences.

If you're interested in learning more about visual thinking, I highly recommend these resources:

Edward Tufte's Work

The Doodle Revolution, by Sunni Brown

Unflattening, by Nick Sousanis