Post pobrano z: Advice for Technical Writing

In advance of a recent podcast with the incredible technical writer and Smashing Magazine editor-in-chief Rachel Andrew, I gathered up a bunch of thoughts and references on the subject of technical writing. So many smart people have said a lot of smart things over the years that I thought I’d round up some of my favorite advice and sprinkle in my own experiences, as someone who has also done his fair share of technical writing and editing.

There is a much larger world of technical writing out there. My experience and interest is largely about web technology and blogging, so I’m coming at it from that angle and many of the people I quote throughout are in that same boat.

Picking something to write about

If you want to write for CSS-Tricks and you ask me what you should write about, I’m probably going to turn that question around on you. It’s likely I don’t know you well enough to pick the perfect topic for you. More importantly, what I really want you to write about is something that is personal and important to you. Articles rooted in recent excitement about a particular idea or technology always come out better than dictated assignments.

My best advice:

Write the article you wish you found when you googled something.

— Chris Coyier (@chriscoyier) October 30, 2017

That said, I do maintain a list of ideas specifically for this site. Any writing can be done on assignment and sometimes that elicits the spark needed for something great and on-target for the audience of a site.

Write at the moment of learning

The moment you learn something is the best time to write. It’s fresh in your mind and you can remember what it was like before you understood it. You also understand what it takes to go from not knowing to knowing it. That’s the journey you need to take people on.

If you don’t have time, at least try to capture the vibe wherever you save your ideas. Don’t just write down „dataset.” Write down some quick notes like, „I didn’t realize DOM elements had a .dataset property for getting and setting data attributes. I wonder if it’s better to use that than getAttribute.” That way, you’ll be able to reload that realization in your brain when you revisit the idea.

What have you learned in just the last few days? I bet there is a blog post there. Manuel Matuzovic does an excellent job of putting this into practice with the „Today I Learned” (TIL) section of his blog.

Comparing technologies is an underused format

Here’s some advice Rachel shared that I don’t see taken advantage of nearly enough:

There is a sweet spot for writing technical posts and tutorials. Write for the professional who hasn't had time to learn that thing yet, and link it back to things they already know. For example explaining a modern JS technique to someone who knows jQuery.

— Rachel Andrew (@rachelandrew) February 20, 2019

Tell me about how this new framework relates to Backbone. Tell me how this CMS relates to WordPress. Tell me how some technology connects to another technology that is safe to assume is more widely understood.

Technology changes a lot, but what technology does doesn’t change all that much.

Careful with that intro

The main comment I add on tutorials I review is to ask for an intro that describes what the tutorial is about. I'm 600 words in and still don't know what the tutorial is about and who it is for. #writing

— Rachel Andrew (@rachelandrew) January 5, 2018

Not getting to the point right at the top of technical articles is a dang epidemic. The start of a technical article is not the time to wax poetic or drop some cliché light philosophy like, „Web design sure has changed a lot.” You don’t have to be boring, but you do need to tell me what this article is going to get into and who it is for.

Brian Rinaldi says:

“Does the title make the article sound interesting?” If the title interests a reader, they’ll typically read the intro and decide, “Is it worth my time reading the whole thing?” A common mistake I see in a lot of technical posts is either too much introduction or, alternatively, far too little.

A single well-written paragraph can set the stage for a technical blog post.

Careful with the title, too

I remember a conversation from years ago with content strategist Erin Kissane where she strongly advised me to choose boring titles for everything. Not just the title of blog posts, but for everything, including the names of sections, tags, and even subheadings within posts.

Here’s the thing with boring: it works. Boring isn’t the right word either; it’s clarity. The world is full of clickbait, and maybe that’s effective in some genres, but technical blogging isn’t one of them.

A nice clear blog post title: Getting Started with GraphQL, Phoenix, and React by Margaret Williford

A terrible version of the same: Build a web app with modern technologies in 30 minutes!

What’s a web app? What technologies? What’s modern about them? What’s with the weird time limit?

SEO matters and Margaret’s article is going to do a lot better in both the short and long term with that clear title.

The outro

Ben Halpern says that the next most important thing after the intro is:

[…] the last paragraph.

People don’t read top-to-bottom the moment when they arrive, so there is a good chance it’s the second paragraph people read. Personally, I find the beginning a lot more important than the ending, but there is a certain art to the ending as well.

A lot of people just <h2>Conclusion</h2> and write a few words about what was just went over. Honestly, I don’t hate that. It falls into this time tested pattern:

1. Tell ’em what you’re gonna tell ’em
2. Tell ’em
3. Tell ’em what you told ’em

That helps your message sink in and brings things full circle. Technical blogging isn’t terribly different from marketing in that sense. You’re trying to get people to understand something and you’re using whatever tricks you need to to get the job done. A little repetition is a classic trick.

Make it scannable

Brian Rinaldi says:

[…] the wall of text can be easily be made less intimidating and appear much more visually appealing through the use of visual elements that break it up. The easiest is to simply place section subheadings throughout your post.

I agree: subheadings are probably the easiest and most powerful trick for scannability.

Other methods:

• Lists: Like what I’m doing right now! I didn’t have to use a list. Paragraphs might have worked as well, but a list makes contextual sense here and is probably tricking some of you into reading this. Or at least scanning it and getting some key points in the process.
• Images: Please make them relevant and contextual. Skip the funny GIF. Screenshots are often great in a technical context because they provide a visual to what might otherwise be a difficult concept to explain. I like Unsplash for thematic imagery, too, but you can do better than a random picture of trees, a woman drinking coffee, or a random rack of servers.
• Illustrations: The abstract nature of an illustration is your friend. It tricks people into having a quick thought about what you are describing. They generally take a little work to pull off, but the pay-off for you and the reader can be huge.
• Videos: You can’t simply drop a 42-minute video in the middle of a blog post, but if you can make it clear that you are demonstrating something visual and the video is less than a minute, it can be a powerful choice. You’ve always got <video autoplay muted loop controls> as well to make it GIF-like.
• Blocks of code: Technical blog posts are often about code. Don’t avoid code, embrace it. I love how Dan Abramov sprinkles in code blocks in blog posts not so much to demonstrate syntax and setup, but to make points. I’m going to recommend Embedded Pens as well, because they’re fully interactive demoes in addition to serving as code blocks.
• Tables: Don’t forget about tabular data! Presenting information (particularly data or definitions) in a table makes it more understandable than it would have been any other way.
• Collapsing sections: The <details>/<summary> elements make quick work of collapsible content. If you’ve got a large section of content that is good to be there but doesn’t need to be read by everyone, collapse it! Our reference guide of media queries for devices is a decent example of this in action.

Whatever you pick here, you should pick things that help enhance the points you’re making even if in some ways it feels like trickery. It’s trickery to help readability, and that’s a good thing.

My favorite technique? A little bit of design. Use design principals like spacing, color, and alignment to help the readability of posts. We even go so far as to art direct some posts where design can enhance the central point being made.

The point here isn’t to do away with walls of text altogether. Sometimes that’s exactly what’s needed because you’re asking a reader to deeply read a passage that they otherwise wouldn’t get what’s needed from the content. However, more often than not, a post can strongly benefit from some healthy use of white space.

Use an active voice

I find this one a little tricky to wrap my head around, but Katy Decorah has a great presentation about technical writing that explains this point in great detail. It’s kinda like using present tense and stating a point directly rather than passively.

Passive: „After the file is downloaded…”
Active: „After you download the file…”

Passive: „The request is processed by the server.”
Active: „The server processes the request.”

Here’s another clear explanation with examples by Neal Whitman, read by Mignon Fogarty (Grammar Girl):

There are lots of words to avoid

„Just” is a big one. Brad Frost:

“Just” makes me feel like an idiot. “Just” presumes I come from a specific background, studied certain courses in university, am fluent in certain technologies, and have read all the right books, articles, and resources. “Just” is a dangerous word.

There are plenty of others to avoid, which which I’ve written about before. Read the comments in that last link. Long story short: there are lots of words that do more harm than good in technical writing, not only because they can come across as preachy, but because they usually don’t help the sentences where they’re used. Try taking „just” out of any sentence. The sentence will still make sense without it.

Be mindful of your tone

Tone is concerned with how you say something in consideration of the context. For example, you wouldn’t deliver bad news to someone with a happy tone. The way you express yourself ought to be aligned with the situation.

This is our tone goal on this site:

Friendly. Authoritative. Welcoming. We’re all in this together. Flexible (nondogmatic about ideas). Thankful.

MailChimp has a very extensive guide to theirs.

It’s worth pointing out that tone and voice are separate concepts. I like to think of voice as never changing (it’s your personality which is a part of who you are) while tone changes to suit the context. In other words, you can have a professional voice while communicating in a friendly tone.

I don’t think there is one true tone that is perfect for technical writing, but since the high-level goal of any technical writing is to help someone understand something complicated, you can use tone to help. A joke in the middle of a set of intricate steps is confusing. A bunch! of! excitement! about something might feel out of place or disingenuous, but being drab and lifeless is worse. I’d say if you’re writing under your own name, let’s feel a little bit of your personality as long as it’s not at the cost of clarity. If you’re writing under a brand, match what they have established whether it has been codified or not.

Careful about length

The general tendency in technical writing is to write too much rather than too little. Wade Christensen:

Whether trained by school assignments with word minimums or just uncritical, most of us write too much. Beyond approaching each draft with a ruthless cutting mentality, there are several ways to write short from draft one.

Word limits can help, even if they’re self-imposed.

I heard from a fledgling editor recently who struggled with his writers submitting posts with high word counts, so he suggested they keep it to 1000-1500 as a guideline and that seemed effective. This post is roughly double the high end there, for comparison.

The real solution, if the resources are there, is ruthless editing.

I personally don’t find that writing too long is the only issue. I’ve had just as many occurrences of writers going too short and not digging into the topic deep enough. I don’t like focusing on the length; I like focusing on the clarity of the delivery and usefulness of the content itself.

Side note: Breaking up a post into multiple parts (as separate posts in a series) is not a solution for posts that are too long. In fact, it can exacerbate the problem. Do that only if the different parts are thematically different and can stand alone without the other parts.

Don’t stop yourself from writing

There is an invisible force, built from fear, that keeps a lot of people away from technical blogging. „Meh, everybody already knows this,” you might think. (They don’t). „What if I’m wrong and someone calls me out?” (You aren’t wrong if what you’re doing is working for you.)

There can still be blockers even if you overcome those fears and start putting words to screen. Here’s Max Böck:

There is a thing that happens to me while writing. I start with a fresh idea, excited to shape it into words. But as time passes, I lose confidence.

The trick for Max is not to wait too long and to ignore feelings holding you back:

I’ll publish something as soon as I feel confident that all the important points I want to get across are there. I try to ignore the voice screaming “it’s not ready” just for long enough to push it online.

Jeremy Keith goes so far to say we shouldn’t even keep drafts:

I think keeping drafts can be counterproductive. The problem is that, once something is a draft rather than a blog post, it’s likely to stay a draft and never become a blog post. And the longer something stays in draft, the less likely it is to ever see the light of day.

The chances that your writing helps someone is pretty high! Matthias Ott:

Even the smallest post can help someone else out there.

Think you’re too inexperienced? You’re probably not, but even if you were, a perspective from someone with less experience is still useful. Ali Spittel:

If you have a blog post that contains mostly correct information, or at least your interpretation of the topic, then you’re experienced enough. There are lots of excellent posts out there from the perspective of newbies, and they’re really important!

Fear is a real thing in writing and dealing with it can be debilitating. While it’s primarily geared toward creative writing, The War of Art by Stephen Pressfield is a good read to help break through the fear.

There is no one perfect style

We each have our own unique perspectives and writing styles. One writing style might be more approachable to some, and can therefore help and benefit a large (or even small) number of people in ways you might not expect.

…says Sara Soueidan. She continues:

Just write.

Even if only one person learns something from your article, you’ll feel great, and that you’ve contributed — even if just a little bit — to this amazing community that we’re all constantly learning from.

Technical blog posts don’t have to be devoid of creativity. You could create a wonderful technical blog post that is an annotated chat room conversation between two developers learning from each other. Or a blog post that is a series of videos that build on each other.

The more introductory, the higher the bar

The web is saturated with beginner-rated and surface-level blog posts. There’s a sea of crash courses, 101s, and intros out there. You’ve gotta knock it out of the park if you want to stand out from the pack and be useful.

There is no particular change in tone necessarily for a beginner-focused post. You don’t need to do the equivalent of talking slowly or talking down. You only need to be clear, and clarity is valuable to readers at any skill level, not to mention appreciated by them as well. A very advanced programmer can and will appreciate the clarity in a technical blog post even if it’s something they already understand.

But the bar isn’t that high in general

You don’t need a decade of experience to write a blog post. I’d say it’s closer to a day of experience, a desire to write, and having something to say. I think you’d be surprised at how little you need to do to make a blog post stand out and be read. Put in some effort, make clear points, focus on readability, and you will do well.

I hope the advice in this post helps!

Abstraction is helpful, but real-world examples are sometimes better

Christine writes:

It’s one thing to describe a high-level concept, and another to explain or illustrate how that concept applies to the real world. In technical writing, you’ll often be covering complex or hard-to-understand subjects, so it’s even more important to use a well-placed example or two to showcase why your topic matters, or how it relates to the real world.

I find myself pushing back on code that is too abstract more than I push back on code that is too focused on a real-world use case. I’d rather see ["Charles Adok", "Samantha Frederick"] than ["foo", "bar"] or [a, b] any day, but more importantly, what is then done with that data to make it feel like a relatable programming scenario.

But avoid real-world examples that come at the cost of clarity. If abstraction is useful to drive a complex point home without getting lost in the details, so be it.

Blogging opens doors

Everyone I’ve ever met who had ever actively blogged has said that blogging has had a positive impact on their career. Besides being a public demonstration of your ability to think and present ideas, it helps you understand things better. To teach is to learn.

I’d attribute my own blogging as the biggest contributor to any success I’ve had. Here’s Khoi Vinh, a designer ten times more successful than I’ll ever be:

It’s hard to overstate how important my blog has been, but if I were to try to distill it down into one word, it would be: “amplifier.”

You get better at what you do.

There is no way around it: practice makes you better. The expectations around practice are sometimes very clear and culturally ingrained. In order to get better at playing the piano, you take piano lessons and practice. We all know this. But people also say „Oh, I’m a terrible cook,” as if cooking as a skill is somehow fundamentally different than playing the piano and doesn’t require the same amount of learning and practice.

You get better at writing by writing more. That is, writing with stakes. Writing and then publicly publishing what you write such that people read it.

You can go to school for writing. You could get a writing coach. My thinking is nothing teaches better than writing often. Whatever it is you sink time into is what you end up getting good at. Is 10,000 hours a good framework for you? Go with it. Heck, I find even people that sit around watching a lot of TV end up being pretty damn good at watching TV.

Your voice alone < A story with context < Stories including others < Research and data along with stories including others

An article where you just say some stuff is OK. You’re allowed to say stuff.

But you can do better.

An article where you tell a true story about how something worked for you is better. Context! Now we can better understand where you are coming from when you say your stuff. Plus everybody likes a story.

An article where you combine that with quoting other people’s writing and stories is even better. Now you’re painting a larger picture and helping validate what you’re saying. Context and flavor!

An article where you combine all that with research and data is the best. Now you’re being personal, acknowledging a world outside yourself, layering in context, and avoiding being too anecdotal. Kapow! Now you’re writing!

Are you pitching?

Read what the site says about guest writing. Here’s ours.

Not to scare you off, but 90% of submissions are garbage. Maybe 75% is outright spam and another 15% are people that clearly didn’t read anything we had to say about guest posting and are way off base. I can usually tell from the quality of writing in the email itself if they’ll be a good guest blogger.

I say things like that, and then feel compelled to remind you the bar isn’t that high.

Are there any useful tools?

There probably is, but I don’t wanna link you off to tools I can’t vouch for. All I use is Dropbox Paper for collaborative writing because the sharing model is easy and allows for co-editing and commenting. Plus Grammarly because it catches a ton of mistakes as you go.

📝🎉

The post Advice for Technical Writing appeared first on CSS-Tricks.

Post pobrano z: Advice for Technical Writing

In advance of a recent podcast with the incredible technical writer and Smashing Magazine editor-in-chief Rachel Andrew, I gathered up a bunch of thoughts and references on the subject of technical writing. So many smart people have said a lot of smart things over the years that I thought I’d round up some of my favorite advice and sprinkle in my own experiences, as someone who has also done his fair share of technical writing and editing.

There is a much larger world of technical writing out there. My experience and interest is largely about web technology and blogging, so I’m coming at it from that angle and many of the people I quote throughout are in that same boat.

Picking something to write about

If you want to write for CSS-Tricks and you ask me what you should write about, I’m probably going to turn that question around on you. It’s likely I don’t know you well enough to pick the perfect topic for you. More importantly, what I really want you to write about is something that is personal and important to you. Articles rooted in recent excitement about a particular idea or technology always come out better than dictated assignments.

My best advice:

Write the article you wish you found when you googled something.

— Chris Coyier (@chriscoyier) October 30, 2017

That said, I do maintain a list of ideas specifically for this site. Any writing can be done on assignment and sometimes that elicits the spark needed for something great and on-target for the audience of a site.

Write at the moment of learning

The moment you learn something is the best time to write. It’s fresh in your mind and you can remember what it was like before you understood it. You also understand what it takes to go from not knowing to knowing it. That’s the journey you need to take people on.

If you don’t have time, at least try to capture the vibe wherever you save your ideas. Don’t just write down „dataset.” Write down some quick notes like, „I didn’t realize DOM elements had a .dataset property for getting and setting data attributes. I wonder if it’s better to use that than getAttribute.” That way, you’ll be able to reload that realization in your brain when you revisit the idea.

What have you learned in just the last few days? I bet there is a blog post there. Manuel Matuzovic does an excellent job of putting this into practice with the „Today I Learned” (TIL) section of his blog.

Comparing technologies is an underused format

Here’s some advice Rachel shared that I don’t see taken advantage of nearly enough:

There is a sweet spot for writing technical posts and tutorials. Write for the professional who hasn't had time to learn that thing yet, and link it back to things they already know. For example explaining a modern JS technique to someone who knows jQuery.

— Rachel Andrew (@rachelandrew) February 20, 2019

Tell me about how this new framework relates to Backbone. Tell me how this CMS relates to WordPress. Tell me how some technology connects to another technology that is safe to assume is more widely understood.

Technology changes a lot, but what technology does doesn’t change all that much.

Careful with that intro

The main comment I add on tutorials I review is to ask for an intro that describes what the tutorial is about. I'm 600 words in and still don't know what the tutorial is about and who it is for. #writing

— Rachel Andrew (@rachelandrew) January 5, 2018

Not getting to the point right at the top of technical articles is a dang epidemic. The start of a technical article is not the time to wax poetic or drop some cliché light philosophy like, „Web design sure has changed a lot.” You don’t have to be boring, but you do need to tell me what this article is going to get into and who it is for.

Brian Rinaldi says:

“Does the title make the article sound interesting?” If the title interests a reader, they’ll typically read the intro and decide, “Is it worth my time reading the whole thing?” A common mistake I see in a lot of technical posts is either too much introduction or, alternatively, far too little.

A single well-written paragraph can set the stage for a technical blog post.

Careful with the title, too

I remember a conversation from years ago with content strategist Erin Kissane where she strongly advised me to choose boring titles for everything. Not just the title of blog posts, but for everything, including the names of sections, tags, and even subheadings within posts.

Here’s the thing with boring: it works. Boring isn’t the right word either; it’s clarity. The world is full of clickbait, and maybe that’s effective in some genres, but technical blogging isn’t one of them.

A nice clear blog post title: Getting Started with GraphQL, Phoenix, and React by Margaret Williford

A terrible version of the same: Build a web app with modern technologies in 30 minutes!

What’s a web app? What technologies? What’s modern about them? What’s with the weird time limit?

SEO matters and Margaret’s article is going to do a lot better in both the short and long term with that clear title.

The outro

Ben Halpern says that the next most important thing after the intro is:

[…] the last paragraph.

People don’t read top-to-bottom the moment when they arrive, so there is a good chance it’s the second paragraph people read. Personally, I find the beginning a lot more important than the ending, but there is a certain art to the ending as well.

A lot of people just <h2>Conclusion</h2> and write a few words about what was just went over. Honestly, I don’t hate that. It falls into this time tested pattern:

1. Tell ’em what you’re gonna tell ’em
2. Tell ’em
3. Tell ’em what you told ’em

That helps your message sink in and brings things full circle. Technical blogging isn’t terribly different from marketing in that sense. You’re trying to get people to understand something and you’re using whatever tricks you need to to get the job done. A little repetition is a classic trick.

Make it scannable

Brian Rinaldi says:

[…] the wall of text can be easily be made less intimidating and appear much more visually appealing through the use of visual elements that break it up. The easiest is to simply place section subheadings throughout your post.

I agree: subheadings are probably the easiest and most powerful trick for scannability.

Other methods:

• Lists: Like what I’m doing right now! I didn’t have to use a list. Paragraphs might have worked as well, but a list makes contextual sense here and is probably tricking some of you into reading this. Or at least scanning it and getting some key points in the process.
• Images: Please make them relevant and contextual. Skip the funny GIF. Screenshots are often great in a technical context because they provide a visual to what might otherwise be a difficult concept to explain. I like Unsplash for thematic imagery, too, but you can do better than a random picture of trees, a woman drinking coffee, or a random rack of servers.
• Illustrations: The abstract nature of an illustration is your friend. It tricks people into having a quick thought about what you are describing. They generally take a little work to pull off, but the pay-off for you and the reader can be huge.
• Videos: You can’t simply drop a 42-minute video in the middle of a blog post, but if you can make it clear that you are demonstrating something visual and the video is less than a minute, it can be a powerful choice. You’ve always got <video autoplay muted loop controls> as well to make it GIF-like.
• Blocks of code: Technical blog posts are often about code. Don’t avoid code, embrace it. I love how Dan Abramov sprinkles in code blocks in blog posts not so much to demonstrate syntax and setup, but to make points. I’m going to recommend Embedded Pens as well, because they’re fully interactive demoes in addition to serving as code blocks.
• Tables: Don’t forget about tabular data! Presenting information (particularly data or definitions) in a table makes it more understandable than it would have been any other way.
• Collapsing sections: The <details>/<summary> elements make quick work of collapsible content. If you’ve got a large section of content that is good to be there but doesn’t need to be read by everyone, collapse it! Our reference guide of media queries for devices is a decent example of this in action.

Whatever you pick here, you should pick things that help enhance the points you’re making even if in some ways it feels like trickery. It’s trickery to help readability, and that’s a good thing.

My favorite technique? A little bit of design. Use design principals like spacing, color, and alignment to help the readability of posts. We even go so far as to art direct some posts where design can enhance the central point being made.

The point here isn’t to do away with walls of text altogether. Sometimes that’s exactly what’s needed because you’re asking a reader to deeply read a passage that they otherwise wouldn’t get what’s needed from the content. However, more often than not, a post can strongly benefit from some healthy use of white space.

Use an active voice

I find this one a little tricky to wrap my head around, but Katy Decorah has a great presentation about technical writing that explains this point in great detail. It’s kinda like using present tense and stating a point directly rather than passively.

Passive: „After the file is downloaded…”
Active: „After you download the file…”

Passive: „The request is processed by the server.”
Active: „The server processes the request.”

Here’s another clear explanation with examples by Neal Whitman, read by Mignon Fogarty (Grammar Girl):

There are lots of words to avoid

„Just” is a big one. Brad Frost:

“Just” makes me feel like an idiot. “Just” presumes I come from a specific background, studied certain courses in university, am fluent in certain technologies, and have read all the right books, articles, and resources. “Just” is a dangerous word.

There are plenty of others to avoid, which which I’ve written about before. Read the comments in that last link. Long story short: there are lots of words that do more harm than good in technical writing, not only because they can come across as preachy, but because they usually don’t help the sentences where they’re used. Try taking „just” out of any sentence. The sentence will still make sense without it.

Be mindful of your tone

Tone is concerned with how you say something in consideration of the context. For example, you wouldn’t deliver bad news to someone with a happy tone. The way you express yourself ought to be aligned with the situation.

This is our tone goal on this site:

Friendly. Authoritative. Welcoming. We’re all in this together. Flexible (nondogmatic about ideas). Thankful.

MailChimp has a very extensive guide to theirs.

It’s worth pointing out that tone and voice are separate concepts. I like to think of voice as never changing (it’s your personality which is a part of who you are) while tone changes to suit the context. In other words, you can have a professional voice while communicating in a friendly tone.

I don’t think there is one true tone that is perfect for technical writing, but since the high-level goal of any technical writing is to help someone understand something complicated, you can use tone to help. A joke in the middle of a set of intricate steps is confusing. A bunch! of! excitement! about something might feel out of place or disingenuous, but being drab and lifeless is worse. I’d say if you’re writing under your own name, let’s feel a little bit of your personality as long as it’s not at the cost of clarity. If you’re writing under a brand, match what they have established whether it has been codified or not.

Careful about length

The general tendency in technical writing is to write too much rather than too little. Wade Christensen:

Whether trained by school assignments with word minimums or just uncritical, most of us write too much. Beyond approaching each draft with a ruthless cutting mentality, there are several ways to write short from draft one.

Word limits can help, even if they’re self-imposed.

I heard from a fledgling editor recently who struggled with his writers submitting posts with high word counts, so he suggested they keep it to 1000-1500 as a guideline and that seemed effective. This post is roughly double the high end there, for comparison.

The real solution, if the resources are there, is ruthless editing.

I personally don’t find that writing too long is the only issue. I’ve had just as many occurrences of writers going too short and not digging into the topic deep enough. I don’t like focusing on the length; I like focusing on the clarity of the delivery and usefulness of the content itself.

Side note: Breaking up a post into multiple parts (as separate posts in a series) is not a solution for posts that are too long. In fact, it can exacerbate the problem. Do that only if the different parts are thematically different and can stand alone without the other parts.

Don’t stop yourself from writing

There is an invisible force, built from fear, that keeps a lot of people away from technical blogging. „Meh, everybody already knows this,” you might think. (They don’t). „What if I’m wrong and someone calls me out?” (You aren’t wrong if what you’re doing is working for you.)

There can still be blockers even if you overcome those fears and start putting words to screen. Here’s Max Böck:

There is a thing that happens to me while writing. I start with a fresh idea, excited to shape it into words. But as time passes, I lose confidence.

The trick for Max is not to wait too long and to ignore feelings holding you back:

I’ll publish something as soon as I feel confident that all the important points I want to get across are there. I try to ignore the voice screaming “it’s not ready” just for long enough to push it online.

Jeremy Keith goes so far to say we shouldn’t even keep drafts:

I think keeping drafts can be counterproductive. The problem is that, once something is a draft rather than a blog post, it’s likely to stay a draft and never become a blog post. And the longer something stays in draft, the less likely it is to ever see the light of day.

The chances that your writing helps someone is pretty high! Matthias Ott:

Even the smallest post can help someone else out there.

Think you’re too inexperienced? You’re probably not, but even if you were, a perspective from someone with less experience is still useful. Ali Spittel:

If you have a blog post that contains mostly correct information, or at least your interpretation of the topic, then you’re experienced enough. There are lots of excellent posts out there from the perspective of newbies, and they’re really important!

Fear is a real thing in writing and dealing with it can be debilitating. While it’s primarily geared toward creative writing, The War of Art by Stephen Pressfield is a good read to help break through the fear.

There is no one perfect style

We each have our own unique perspectives and writing styles. One writing style might be more approachable to some, and can therefore help and benefit a large (or even small) number of people in ways you might not expect.

…says Sara Soueidan. She continues:

Just write.

Even if only one person learns something from your article, you’ll feel great, and that you’ve contributed — even if just a little bit — to this amazing community that we’re all constantly learning from.

Technical blog posts don’t have to be devoid of creativity. You could create a wonderful technical blog post that is an annotated chat room conversation between two developers learning from each other. Or a blog post that is a series of videos that build on each other.

The more introductory, the higher the bar

The web is saturated with beginner-rated and surface-level blog posts. There’s a sea of crash courses, 101s, and intros out there. You’ve gotta knock it out of the park if you want to stand out from the pack and be useful.

There is no particular change in tone necessarily for a beginner-focused post. You don’t need to do the equivalent of talking slowly or talking down. You only need to be clear, and clarity is valuable to readers at any skill level, not to mention appreciated by them as well. A very advanced programmer can and will appreciate the clarity in a technical blog post even if it’s something they already understand.

But the bar isn’t that high in general

You don’t need a decade of experience to write a blog post. I’d say it’s closer to a day of experience, a desire to write, and having something to say. I think you’d be surprised at how little you need to do to make a blog post stand out and be read. Put in some effort, make clear points, focus on readability, and you will do well.

I hope the advice in this post helps!

Abstraction is helpful, but real-world examples are sometimes better

Christine writes:

It’s one thing to describe a high-level concept, and another to explain or illustrate how that concept applies to the real world. In technical writing, you’ll often be covering complex or hard-to-understand subjects, so it’s even more important to use a well-placed example or two to showcase why your topic matters, or how it relates to the real world.

I find myself pushing back on code that is too abstract more than I push back on code that is too focused on a real-world use case. I’d rather see ["Charles Adok", "Samantha Frederick"] than ["foo", "bar"] or [a, b] any day, but more importantly, what is then done with that data to make it feel like a relatable programming scenario.

But avoid real-world examples that come at the cost of clarity. If abstraction is useful to drive a complex point home without getting lost in the details, so be it.

Blogging opens doors

Everyone I’ve ever met who had ever actively blogged has said that blogging has had a positive impact on their career. Besides being a public demonstration of your ability to think and present ideas, it helps you understand things better. To teach is to learn.

I’d attribute my own blogging as the biggest contributor to any success I’ve had. Here’s Khoi Vinh, a designer ten times more successful than I’ll ever be:

It’s hard to overstate how important my blog has been, but if I were to try to distill it down into one word, it would be: “amplifier.”

You get better at what you do.

There is no way around it: practice makes you better. The expectations around practice are sometimes very clear and culturally ingrained. In order to get better at playing the piano, you take piano lessons and practice. We all know this. But people also say „Oh, I’m a terrible cook,” as if cooking as a skill is somehow fundamentally different than playing the piano and doesn’t require the same amount of learning and practice.

You get better at writing by writing more. That is, writing with stakes. Writing and then publicly publishing what you write such that people read it.

You can go to school for writing. You could get a writing coach. My thinking is nothing teaches better than writing often. Whatever it is you sink time into is what you end up getting good at. Is 10,000 hours a good framework for you? Go with it. Heck, I find even people that sit around watching a lot of TV end up being pretty damn good at watching TV.

Your voice alone < A story with context < Stories including others < Research and data along with stories including others

An article where you just say some stuff is OK. You’re allowed to say stuff.

But you can do better.

An article where you tell a true story about how something worked for you is better. Context! Now we can better understand where you are coming from when you say your stuff. Plus everybody likes a story.

An article where you combine that with quoting other people’s writing and stories is even better. Now you’re painting a larger picture and helping validate what you’re saying. Context and flavor!

An article where you combine all that with research and data is the best. Now you’re being personal, acknowledging a world outside yourself, layering in context, and avoiding being too anecdotal. Kapow! Now you’re writing!

Are you pitching?

Read what the site says about guest writing. Here’s ours.

Not to scare you off, but 90% of submissions are garbage. Maybe 75% is outright spam and another 15% are people that clearly didn’t read anything we had to say about guest posting and are way off base. I can usually tell from the quality of writing in the email itself if they’ll be a good guest blogger.

I say things like that, and then feel compelled to remind you the bar isn’t that high.

Are there any useful tools?

There probably is, but I don’t wanna link you off to tools I can’t vouch for. All I use is Dropbox Paper for collaborative writing because the sharing model is easy and allows for co-editing and commenting. Plus Grammarly because it catches a ton of mistakes as you go.

📝🎉

The post Advice for Technical Writing appeared first on CSS-Tricks.

Post pobrano z: Jeremy Keith – Building the Web

I really enjoyed this interview with Jeremy Keith on the state of the web, how things have changed in recent years and why he’s a mix of optimistic and nervous for the future.

One thing that caught my attention during the interview more than anything was where Jeremy started discussing how folks think that websites are pretty crummy in general. This reminded me that I cannot count the number of times when someone has said to me “ah, I can’t view this website on my phone.”

We have websites that aren’t responsive! We have websites that litter the UI with advertisements and modals! And we have websites that are slow as all heck just when we need them the most!

Of course folks are going to start complaining about the web and working around them if they find that this is the case. I’ll even catch myself sending an email to myself when I know that the mobile experience is going to be crummy. Or I’ll Instapaper something because the design of the website is particularly difficult to read. Remember, Reader Mode is the button to beat.

My quick thought on this is that we shouldn’t become sour and pessimistic. We should roll up our sleeves and get to work because clearly there’s much left to do.

Direct Link to Article — Permalink

The post Jeremy Keith – Building the Web appeared first on CSS-Tricks.

Post pobrano z: Jeremy Keith – Building the Web

I really enjoyed this interview with Jeremy Keith on the state of the web, how things have changed in recent years and why he’s a mix of optimistic and nervous for the future.

One thing that caught my attention during the interview more than anything was where Jeremy started discussing how folks think that websites are pretty crummy in general. This reminded me that I cannot count the number of times when someone has said to me “ah, I can’t view this website on my phone.”

We have websites that aren’t responsive! We have websites that litter the UI with advertisements and modals! And we have websites that are slow as all heck just when we need them the most!

Of course folks are going to start complaining about the web and working around them if they find that this is the case. I’ll even catch myself sending an email to myself when I know that the mobile experience is going to be crummy. Or I’ll Instapaper something because the design of the website is particularly difficult to read. Remember, Reader Mode is the button to beat.

My quick thought on this is that we shouldn’t become sour and pessimistic. We should roll up our sleeves and get to work because clearly there’s much left to do.

Direct Link to Article — Permalink

The post Jeremy Keith – Building the Web appeared first on CSS-Tricks.

Post pobrano z: Multiplayer Tic Tac Toe with GraphQL

GraphQL is a query language for APIs that is very empowering for front-end developers. As the GraphQL site explains it, you describe your data, ask for what you want, and get predictable results.

If you haven’t worked with it before, GraphQL might be a little confusing to grok at first glance. So, let’s build a multiplayer tic-tac-toe game using it in order to demonstrate how it’s used and what we can do with it.

First thing we need is a backend for our APIs. We’re going to use Hasura GraphQL Engine along with a custom GraphQL server for this tutorial. We’ll look at the queries and mutations that the client-side needs to build the game. You can implement this kind of thing in whatever framework you wish, but we’re going with use React and Apollo for this tutorial.

Here’s what we’re making:

GitHub Repo

A brief GraphQL primer

GraphQL is a query language for APIs; a language with a syntax that defines a way to fetch data from the server. It works with any kind of API that is backed by a strong system that makes your codebase resilient. Some of the primary characteristics of GraphQL are:

• The client can ask the server for what queries it supports (check out introspection for more).
• The client must ask the server for exactly what it wants. It can’t ask for something like a wildcard (*) but rather exact fields. For example, to get a user’s ID and name, the GraphQL query would be something like:

  query {
    user {
      id
      name
    }
  }

• Every query is made to a single endpoint and every request is a POST request.
• Given a query, the structure of the response is enforced. For example, for the above query to get the id and name of a user object, a successful response would be something like:

  {
    "data": {
      "user": {
        "id": "AUTH:482919",
        "name": "Jon Doe"
      }
    }
  }

This series of articles is a great place to start if you want to know more about GraphQL.

Why are we using GraphQL, anyway?

We just discussed how GraphQL demands that the client must ask the server for exactly what it wants. That means there is no unnecessary data retrieved from the server, like in case of REST where you would receive a huge response even when you need one field. Getting what new need and only what we need optimizes responses so that they’re speedy and predictable.

The client can ask the server for its schema via introspection. This schema can be used to build queries dynamically using an API explorer like GraphiQL. It also enables linting and auto-completing because every query can be built with and cross-checked against the GraphQL schema. As a front-end developer, this greatly enhances the DX as there is much less human error involved.

Since there is a single endpoint and every request is a POST request, GraphQL can avoid a lot of boilerplate since it doesn’t have to track endpoints, request payloads and response types. Response caching is much easier because every query response can be expected to be of a certain structure.

Furthermore, GraphQL has a well-defined spec for implementing real-time subscriptions. You do not have to come up with your own implementation details for building real-time servers. Build a server that complies with GraphQL’s real-time spec and any client can start consuming the real-time GraphQL APIs with ease.

GraphQL Terminology

I will be using some GraphQL terms in this post, so it’s worth covering a few of them here in advance.

• Query: A GraphQL query is one that simply fetches data from the server.
• Mutation: This is a GraphQL query that changes something on the server and fetches some data.
• Subscription: This is a GraphQL query that subscribes the client to some changes on the server.
• Query variables: These allow us to add parameters to a GraphQL query.

Getting back to the backend

Now that we have a cursory understanding of GraphQL, let’s start with modeling a backend. Our GraphQL backend would be a combination of Hasura GraphQL Engine and a custom GraphQL server. We will not go into the subtleties of code in this case.

Since Tic Tac Toe is a multiplayer game, there is a need to store state in the database. We will use Postgres as our database and Hasura GraphQL Engine as a GraphQL server that allows us to CRUD the data in Postgres over GraphQL.

Apart from CRUD on the database, we would also want to run some custom logic in the form of GraphQL mutations. We will use a custom GraphQL server for that.

Hasura describes itself quite nicely in its README file:

GraphQL Engine is a blazing-fast GraphQL server that gives you instant, realtime GraphQL APIs over Postgres, with webhook triggers on database events, and remote schemas for business logic.

Going a little deeper, Hasura GraphQL Engine is an open-source server that sits on top of a Postgres database and allows you to CRUD the data over real-time GraphQL. It works with both new and existing Postgres databases. It also has an access control layer that you can integrate with any auth provider. In this post though, we will not implement auth for the sake of brevity.

Let’s start by deploying an instance of Hasura GraphQL Engine to Heroku’s free tier that comes with a fresh Postgres database. Go ahead, do it; it is free and you do not need to enter your credit card details 🙂

Once you deploy, you will land up on the Hasura console which is the admin UI to manage your backend. Note that the URL you are at, is your GraphQL Engine URL. Lets start with creating our required tables.

user

A user table will store our users. To create the table, go to the „Data” tab on top and click on the „Create Table” button.

This table has an id column which is the unique identifier of each user and a name column that stores the user’s name.

board

The board table will store the game boards where all the action happens. We’ll spin up a new board for each game that starts.

Lets look at the columns of this table:

• id: A unique UUID for each board that is auto generated
• user_1_id: The user_id of the first user. This user by default plays X in the game
• user_2_id: The user_id of the second user. This user by default plays O.
• winner: This is a text field that is set to X or O once the winner has been decided.
• turn: This is a text field that can be X or O and it stores the current turn. It starts with X.

Since user_1_id and user_2_id store the user IDs, let’s add a constraint on the board table that ensures user_1_id and user_2_id to be present in table user.

Go to the „Modify” tab in the Hasura board table and add the foreign keys.

Now, based on these relationships, we need to create a connection between these tables so that we can query the user information while querying the board.

Go to the „Relationships” tab in Hasura and create relationships called user1 and user2 for user_1_id and user_2_id based suggested relations.

move

Finally, we need a move table that stores the moves made by users on a board.

Let’s look at the columns:

• id: The unique identifier of each move that is auto generated
• user_id: The ID of the user that made the move
• board_id: The ID of the board that the move was made on
• position: The position where the move was made (i.e. 1-9)

Since user_id and board_id are foreign keys to user and board table, respectively. We must create these foreign key constraints just like we did above. Next, create the relationships as user for the foreign key on user_id and board for the foreign key on board_id. Then, we’ll go back to the board table’s „Relationship” tab and create the suggested relationship to move table. Call it moves.

We need a custom server

Apart from storing data in the database, we also want to perform custom logic. The logic? Whenever a user makes a move, the move must be validated, made before the turn must is switched.

In order to do that, we must run an SQL transaction on the database. I have written a GraphQL server that does exactly that that I’ve deployed on Glitch.

Now we have two GraphQL servers. But GraphQL spec enforces that there must be only one endpoint. For this purpose, Hasura supports remote schemas — i.e. you can provide an external GraphQL endpoint to Hasura and it will merge this GraphQL server with itself and serve the combined schema under a single endpoint. Let’s add this custom GraphQL server to our Hasura Engine instance:

1. Fork the GraphQL server.
2. Add an environment variable that is the connection to your Postgres database. To do that, go to https://dashboard.heroku.com, choose your app, go to „Settings” and reveal config vars.

A few more steps from there:

1. Copy the value for the DATABASE_URL.
2. Go to the GraphQL server you forked and paste that value in the .env file (POSTGRES_CONNECTION_STRING=<value>).
3. Click on the „Show Live” button on top and copy the opened URL.

We’ll add this URL to GraphQL engine by adding it as a remote schema. Go to the „Remote Schemas” tab on top and click on the „Add” option.

We are done with setting up our backend!

Let’s work on the front end

I will not be going into the details of front-end implementation since y’all would choose to implement it in the framework of your choice. I’ll go ahead and provide all the required queries and mutations that you would need to build the game. Using these with the front-end framework of your choice will allow you to build a fully functional multiplayer Tic Tac Toe.

Setup

Apollo Client is the go-to library for client-side GraphQL. They have awesome abstractions for React, Vue, Angular, iOS, Android etc. It helps you save a lot of boilerplate and the DX is smooth. You might want to consider using Apollo client over doing everything from scratch.

Let’s discuss the queries and mutations that the client would need for this game.

Insert user

In the app that I built, I generated a random username for each user and inserted this name into the database whenever they open the app. I also stored the name and generated a user ID in local storage so that the same user does not have different usernames. The mutation I used is:

mutation ($name:String) {
  insert_user (
    objects: {
      name: $name
    }
  ) {
    returning {
      id
    }
  }
}

This mutation inserts an entry into the user table and returns the generated id. If you observe the mutation closely, it uses $name. This is called the query variable. When you send this mutation to the server along with the variables { "name": "bazooka"}, the GraphQL server would replace $name from the query variables, which in this case would be „bazooka.”

If you wish, you can implement auth and insert into this table with the username or the nickname.

Load all boards

To load all the boards, we run a GraphQL subscription:

subscription {
  board (
    where: {
      _and: {
        winner: {
          _is_null: true
        },
        user_2_id: {
          _is_null: true
        }
      }
    }
    order_by: {
      created_at: asc }
  ) {
    id
    user1 {
      id
      name
    }
    user_2_id
    created_at
    winner
  }
}

This subscription is a live query that returns the id, user1 along with their id and name (from the relationship), user_2_id, winner and created_at. We have set a where filter which fetches us only the boards without a valid winner and where user_2_id is null which means the board is is open for a player to join. Finally, we order these boards by their created_at timestamp.

Creating a board

Users can create boards for other people to join. To do that, they have to insert an entry into the boards table.

mutation ($user_id: Int) {
  insert_board (
    objects: [{
      user_1_id: $user_id,
      turn: "x",
    }]
  ) {
    returning {
      id
    }
  }
}

Joining a board

To join a board, a user needs to update the user_2_id of the board with their own user_id. The mutation looks like:

mutation ($user_id: Int, $board_id: uuid!) {
  update_board (
    _set: {
      user_2_id: $user_id
    },
    where: {
      _and: {
        id: {
          _eq: $board_id
        },
        user_2_id: {
          _is_null: true
        },
        user_1_id: {
          _neq: $user_id
        }
      }
    }
  ) {
    affected_rows
    returning {
      id
    }
  }
}

In the above GraphQL mutation, we are setting the user_2_id of a board to a user_id. We have also added additional checks such that this action succeeds only if the joining player is not the creator and the board is not already full. After the mutation, we ask for the number of affected rows.

In my app, after joining a board, I would redirect users to /play?board_id=<board_id>.

Subscribing to the board

When both users are in game, we need real-time updates about the moves of each player. So we must subscribe to the given board that is being played on and also the moves (through the relationship).

subscription($board_id: uuid!) {
  board: board_by_pk (id: $board_id) {
    id
    moves (order_by: { id: desc}) {
      id
      position
      user {
        id
        name
      }
      user_id
    }
    user1 {
      id
      name
    }
    user2 {
      id
      name
    }
    turn
    winner
  }
}

The above query subscribes the client to the board that is being played. Whenever a new move is played, the client will be updated with it.

Making a move

To make a move, we will be using the make_move mutation from our custom GraphQL server.

mutation (
  $board_id: String!,
  $position: Int!,
  $user_id: Int!
) {
  make_move (
    board_id: $board_id,
    position: $position,
    user_id: $user_id
  ) {
    success
  }
}

This mutation takes a board_id, position and user_id from query variables. It validates the move, makes the move and also switches the turn. In the end, it returns whether this transaction was successful or not.

Tic Tac Whoa!

And now you have a working game of Tic Tac Toe! You can implement any real-time multiplayer game with GraphQL subscriptions using the concepts we covered. Let me know if you have any questions and I would be happy to answer.

The post Multiplayer Tic Tac Toe with GraphQL appeared first on CSS-Tricks.

Post pobrano z: Multiplayer Tic Tac Toe with GraphQL

GraphQL is a query language for APIs that is very empowering for front-end developers. As the GraphQL site explains it, you describe your data, ask for what you want, and get predictable results.

If you haven’t worked with it before, GraphQL might be a little confusing to grok at first glance. So, let’s build a multiplayer tic-tac-toe game using it in order to demonstrate how it’s used and what we can do with it.

First thing we need is a backend for our APIs. We’re going to use Hasura GraphQL Engine along with a custom GraphQL server for this tutorial. We’ll look at the queries and mutations that the client-side needs to build the game. You can implement this kind of thing in whatever framework you wish, but we’re going with use React and Apollo for this tutorial.

Here’s what we’re making:

GitHub Repo

A brief GraphQL primer

GraphQL is a query language for APIs; a language with a syntax that defines a way to fetch data from the server. It works with any kind of API that is backed by a strong system that makes your codebase resilient. Some of the primary characteristics of GraphQL are:

• The client can ask the server for what queries it supports (check out introspection for more).
• The client must ask the server for exactly what it wants. It can’t ask for something like a wildcard (*) but rather exact fields. For example, to get a user’s ID and name, the GraphQL query would be something like:

  query {
    user {
      id
      name
    }
  }

• Every query is made to a single endpoint and every request is a POST request.
• Given a query, the structure of the response is enforced. For example, for the above query to get the id and name of a user object, a successful response would be something like:

  {
    "data": {
      "user": {
        "id": "AUTH:482919",
        "name": "Jon Doe"
      }
    }
  }

This series of articles is a great place to start if you want to know more about GraphQL.

Why are we using GraphQL, anyway?

We just discussed how GraphQL demands that the client must ask the server for exactly what it wants. That means there is no unnecessary data retrieved from the server, like in case of REST where you would receive a huge response even when you need one field. Getting what new need and only what we need optimizes responses so that they’re speedy and predictable.

The client can ask the server for its schema via introspection. This schema can be used to build queries dynamically using an API explorer like GraphiQL. It also enables linting and auto-completing because every query can be built with and cross-checked against the GraphQL schema. As a front-end developer, this greatly enhances the DX as there is much less human error involved.

Since there is a single endpoint and every request is a POST request, GraphQL can avoid a lot of boilerplate since it doesn’t have to track endpoints, request payloads and response types. Response caching is much easier because every query response can be expected to be of a certain structure.

Furthermore, GraphQL has a well-defined spec for implementing real-time subscriptions. You do not have to come up with your own implementation details for building real-time servers. Build a server that complies with GraphQL’s real-time spec and any client can start consuming the real-time GraphQL APIs with ease.

GraphQL Terminology

I will be using some GraphQL terms in this post, so it’s worth covering a few of them here in advance.

• Query: A GraphQL query is one that simply fetches data from the server.
• Mutation: This is a GraphQL query that changes something on the server and fetches some data.
• Subscription: This is a GraphQL query that subscribes the client to some changes on the server.
• Query variables: These allow us to add parameters to a GraphQL query.

Getting back to the backend

Now that we have a cursory understanding of GraphQL, let’s start with modeling a backend. Our GraphQL backend would be a combination of Hasura GraphQL Engine and a custom GraphQL server. We will not go into the subtleties of code in this case.

Since Tic Tac Toe is a multiplayer game, there is a need to store state in the database. We will use Postgres as our database and Hasura GraphQL Engine as a GraphQL server that allows us to CRUD the data in Postgres over GraphQL.

Apart from CRUD on the database, we would also want to run some custom logic in the form of GraphQL mutations. We will use a custom GraphQL server for that.

Hasura describes itself quite nicely in its README file:

GraphQL Engine is a blazing-fast GraphQL server that gives you instant, realtime GraphQL APIs over Postgres, with webhook triggers on database events, and remote schemas for business logic.

Going a little deeper, Hasura GraphQL Engine is an open-source server that sits on top of a Postgres database and allows you to CRUD the data over real-time GraphQL. It works with both new and existing Postgres databases. It also has an access control layer that you can integrate with any auth provider. In this post though, we will not implement auth for the sake of brevity.

Let’s start by deploying an instance of Hasura GraphQL Engine to Heroku’s free tier that comes with a fresh Postgres database. Go ahead, do it; it is free and you do not need to enter your credit card details 🙂

Once you deploy, you will land up on the Hasura console which is the admin UI to manage your backend. Note that the URL you are at, is your GraphQL Engine URL. Lets start with creating our required tables.

user

A user table will store our users. To create the table, go to the „Data” tab on top and click on the „Create Table” button.

This table has an id column which is the unique identifier of each user and a name column that stores the user’s name.

board

The board table will store the game boards where all the action happens. We’ll spin up a new board for each game that starts.

Lets look at the columns of this table:

• id: A unique UUID for each board that is auto generated
• user_1_id: The user_id of the first user. This user by default plays X in the game
• user_2_id: The user_id of the second user. This user by default plays O.
• winner: This is a text field that is set to X or O once the winner has been decided.
• turn: This is a text field that can be X or O and it stores the current turn. It starts with X.

Since user_1_id and user_2_id store the user IDs, let’s add a constraint on the board table that ensures user_1_id and user_2_id to be present in table user.

Go to the „Modify” tab in the Hasura board table and add the foreign keys.

Now, based on these relationships, we need to create a connection between these tables so that we can query the user information while querying the board.

Go to the „Relationships” tab in Hasura and create relationships called user1 and user2 for user_1_id and user_2_id based suggested relations.

move

Finally, we need a move table that stores the moves made by users on a board.

Let’s look at the columns:

• id: The unique identifier of each move that is auto generated
• user_id: The ID of the user that made the move
• board_id: The ID of the board that the move was made on
• position: The position where the move was made (i.e. 1-9)

Since user_id and board_id are foreign keys to user and board table, respectively. We must create these foreign key constraints just like we did above. Next, create the relationships as user for the foreign key on user_id and board for the foreign key on board_id. Then, we’ll go back to the board table’s „Relationship” tab and create the suggested relationship to move table. Call it moves.

We need a custom server

Apart from storing data in the database, we also want to perform custom logic. The logic? Whenever a user makes a move, the move must be validated, made before the turn must is switched.

In order to do that, we must run an SQL transaction on the database. I have written a GraphQL server that does exactly that that I’ve deployed on Glitch.

Now we have two GraphQL servers. But GraphQL spec enforces that there must be only one endpoint. For this purpose, Hasura supports remote schemas — i.e. you can provide an external GraphQL endpoint to Hasura and it will merge this GraphQL server with itself and serve the combined schema under a single endpoint. Let’s add this custom GraphQL server to our Hasura Engine instance:

1. Fork the GraphQL server.
2. Add an environment variable that is the connection to your Postgres database. To do that, go to https://dashboard.heroku.com, choose your app, go to „Settings” and reveal config vars.

A few more steps from there:

1. Copy the value for the DATABASE_URL.
2. Go to the GraphQL server you forked and paste that value in the .env file (POSTGRES_CONNECTION_STRING=<value>).
3. Click on the „Show Live” button on top and copy the opened URL.

We’ll add this URL to GraphQL engine by adding it as a remote schema. Go to the „Remote Schemas” tab on top and click on the „Add” option.

We are done with setting up our backend!

Let’s work on the front end

I will not be going into the details of front-end implementation since y’all would choose to implement it in the framework of your choice. I’ll go ahead and provide all the required queries and mutations that you would need to build the game. Using these with the front-end framework of your choice will allow you to build a fully functional multiplayer Tic Tac Toe.

Setup

Apollo Client is the go-to library for client-side GraphQL. They have awesome abstractions for React, Vue, Angular, iOS, Android etc. It helps you save a lot of boilerplate and the DX is smooth. You might want to consider using Apollo client over doing everything from scratch.

Let’s discuss the queries and mutations that the client would need for this game.

Insert user

In the app that I built, I generated a random username for each user and inserted this name into the database whenever they open the app. I also stored the name and generated a user ID in local storage so that the same user does not have different usernames. The mutation I used is:

mutation ($name:String) {
  insert_user (
    objects: {
      name: $name
    }
  ) {
    returning {
      id
    }
  }
}

This mutation inserts an entry into the user table and returns the generated id. If you observe the mutation closely, it uses $name. This is called the query variable. When you send this mutation to the server along with the variables { "name": "bazooka"}, the GraphQL server would replace $name from the query variables, which in this case would be „bazooka.”

If you wish, you can implement auth and insert into this table with the username or the nickname.

Load all boards

To load all the boards, we run a GraphQL subscription:

subscription {
  board (
    where: {
      _and: {
        winner: {
          _is_null: true
        },
        user_2_id: {
          _is_null: true
        }
      }
    }
    order_by: {
      created_at: asc }
  ) {
    id
    user1 {
      id
      name
    }
    user_2_id
    created_at
    winner
  }
}

This subscription is a live query that returns the id, user1 along with their id and name (from the relationship), user_2_id, winner and created_at. We have set a where filter which fetches us only the boards without a valid winner and where user_2_id is null which means the board is is open for a player to join. Finally, we order these boards by their created_at timestamp.

Creating a board

Users can create boards for other people to join. To do that, they have to insert an entry into the boards table.

mutation ($user_id: Int) {
  insert_board (
    objects: [{
      user_1_id: $user_id,
      turn: "x",
    }]
  ) {
    returning {
      id
    }
  }
}

Joining a board

To join a board, a user needs to update the user_2_id of the board with their own user_id. The mutation looks like:

mutation ($user_id: Int, $board_id: uuid!) {
  update_board (
    _set: {
      user_2_id: $user_id
    },
    where: {
      _and: {
        id: {
          _eq: $board_id
        },
        user_2_id: {
          _is_null: true
        },
        user_1_id: {
          _neq: $user_id
        }
      }
    }
  ) {
    affected_rows
    returning {
      id
    }
  }
}

In the above GraphQL mutation, we are setting the user_2_id of a board to a user_id. We have also added additional checks such that this action succeeds only if the joining player is not the creator and the board is not already full. After the mutation, we ask for the number of affected rows.

In my app, after joining a board, I would redirect users to /play?board_id=<board_id>.

Subscribing to the board

When both users are in game, we need real-time updates about the moves of each player. So we must subscribe to the given board that is being played on and also the moves (through the relationship).

subscription($board_id: uuid!) {
  board: board_by_pk (id: $board_id) {
    id
    moves (order_by: { id: desc}) {
      id
      position
      user {
        id
        name
      }
      user_id
    }
    user1 {
      id
      name
    }
    user2 {
      id
      name
    }
    turn
    winner
  }
}

The above query subscribes the client to the board that is being played. Whenever a new move is played, the client will be updated with it.

Making a move

To make a move, we will be using the make_move mutation from our custom GraphQL server.

mutation (
  $board_id: String!,
  $position: Int!,
  $user_id: Int!
) {
  make_move (
    board_id: $board_id,
    position: $position,
    user_id: $user_id
  ) {
    success
  }
}

This mutation takes a board_id, position and user_id from query variables. It validates the move, makes the move and also switches the turn. In the end, it returns whether this transaction was successful or not.

Tic Tac Whoa!

And now you have a working game of Tic Tac Toe! You can implement any real-time multiplayer game with GraphQL subscriptions using the concepts we covered. Let me know if you have any questions and I would be happy to answer.

The post Multiplayer Tic Tac Toe with GraphQL appeared first on CSS-Tricks.