A Starting Point for Writing Technical Blog Posts

Elizabeth Schafer — Sun, 28 Apr 2019 13:24:33 +0000

I've accumulated a lot of useful info as a front end developer over the years, and want to be able to share that with others. Unfortunately, teaching doesn't come naturally to me. I feel like I need to simultaneously know everything and teach everything all at once, which of course is impossible. I also have a hard time narrowing down what the most important concepts are because everything seems equally important to me.

When I decided to try writing a technical blog post, I searched around to see if there were any guidelines or best practices I might be able to follow. That's when I came across howtoegghead.com, which is a guide for egghead.io instructors on how to create lessons. I found it really helpful, and highly recommend reading through it if you're looking for guidance.

Here's a summary of the points I found most useful (adapted for blog posts), plus some of my own thoughts. Full disclosure: this is all new to me, and mostly just notes to myself as a way to encourage myself to write more.

Decide what to write about

Some ideas for topics:

something you're passionate about
something you've learned recently, or are in the process of learning
something you've figured out recently (e.g., a confusing bug or unexpected edge case)
something that seems super simple to you, but might be a big help to anyone less experienced

Make sure to narrow this down to something very specific. It should be something you can talk about in just a few minutes. For example, my thought process might be something like this:

I'm passionate about accessibility, so I should write about that! - This is way too broad. I wouldn't even know where to start.
Being able to use a keyboard to navigate a website is important. - A little better, but still too much to cover.
The first thing I notice with keyboard navigation is how important it is for focus states to be visible and easy to spot. - Much better. This is finally something I can start wrapping my head around.
I'll talk specifically about button focus states. Perfect! This sounds pretty simple on the surface, but there's a lot I can talk about.

What I love about this is that I could potentially write a series of short, related posts that each go into detail about one specific thing. It gives me permission to leave out extra details that I feel like I should mention, but don't necessarily contribute to the current topic.

It's totally fine if you want to write about something that other people have already written about. By writing in your own words, you're giving people another viewpoint that might make things click. It's also a great way for you to reinforce what you've learned, and for your future self to reference.

Some of my favorite blog posts are ones that cover the absolute basics of HTML and CSS. These are things that have been covered many times already, but I always learn something new.

It doesn't matter if you're a beginner. If you're a beginner, you might work through things in a way that makes sense to other beginners. Someone more experienced might include a code snippet without explicitly stating which file that code is supposed to go in. Or they might include something to run from the command line without explaining that you first need to be in the right working directory. Those are the types of things I get stuck on when I'm learning something new, and they're usually hard to figure out when you don't know how things work yet.

Be clear and to the point

Assume your readers already have the required background knowledge. If there's anything they don't know, they can look it up on their own.

Don't include an intro, outro, or stage-setting. Think about when you search for a recipe and have to read someone's life story before you find the ingredient list. We want to keep it simple, so include only the content people are looking for.

Show your work

Include a series of editable code examples. It's one thing to read about something, and another to see it in action. Instead of describing everything in words, use code examples to prove your point. Here's an example of what I mean:

By including a series of examples, readers can see each step of the process and how it affects the result. And since these can be edited, readers have the option of playing around with the code to get a better understanding of how things work.

Now you're ready to write!

I put this together because I was having a hard time getting started without a list of guidelines to follow. Now that I have a starting point, I'm hoping it will help make the writing process easier for me in the future.

Are there any resources you use to figure out what to write about or how to structure your posts? Or do you have a specific process you like to follow that works for you? I'd love to learn more about how others are doing this!

One thing I found after writing most of this was Ali Spittel's blog post workflow which goes more in-depth - would've been helpful if I'd noticed that first! 😉

Designing button focus states for better usability

Elizabeth Schafer — Sun, 07 Apr 2019 06:30:46 +0000

Let's say we're making a custom button. The designer hands off the design file, and we write some CSS to make it look exactly right. Pretty straightforward, right?

But wait — buttons have more than one state. The default state we just created looks good so far, but we need to make sure that it also looks noticeably different when it's focused.

Many people exclusively use keyboards to navigate, and rely on the focus state to know where they are on the page.¹

There's a huge variety of reasons why someone might use a keyboard over a mouse, and for many, using the mouse as a fallback just isn't an option.

When you navigate a page with the keyboard, you press tab to go through all the interactive elements on the page. If you have access to a keyboard now, go ahead and try it out. You should be able to easily see what's in focus.

If the focus state isn't visible (or hard to see), it's like trying to use a website with an invisible mouse cursor:

There's no way anyone would think that'd be okay to push to production! But when we don't pay attention to our focus states, that's exactly what we end up doing.

This affects real people in the same way the invisible-cursor example might affect you. If you're sighted, there's also a good chance that you, personally, might end up relying on these focus states as you age (assuming you don't already). Let's fix this!

Browser defaults

Browsers provide focus states by default. Here's what those look like on our custom button:

I don't have vision problems, but most of those are very hard for me to see. It's even worse for people with low vision — for them, there's no visible difference between these focus states and the default button state.

Designing a custom focus state

So what would we need to do to have a focus state that people can see? The main guidelines I use are:

If you're relying on color to signify a change in state, the color contrast ratio between the default color and the focus color needs to be at least 3:1².
Make sure that any outlines are thick enough to actually see. There aren't any official guidelines on this, but at least use something larger than 1px.

Here are some examples of accessible focus states:

Ahh, much better! I realize that a lot of people like things like this to be subtle, but it doesn't really matter what something looks like if you can't use it. This was just a quick proof of concept, so I'm sure there's more creative ways to work within these guidelines that will also fit the aesthetic.

I hope this is useful!

DEV Community: Elizabeth Schafer