✨ newline's Guide to Writing Remarkable Technical Blog Posts ✨
In this guide, we'll talk about what makes a good technical blog post, give examples of quality posts, provide templates, and show a scorecard that you can use to rate your work.If you follow this guide, your blog posts will be clearly structured, easier to understand, and ultimately, remarkable.Being remarkable means that we create something especially good. This can take many forms: a salient insight, unusually good attention to detail, beautiful code, or an "ultimate guide." But oftentimes being remarkable means you've created a solid post that explains the details clearly . All of the details and guidelines below are tools to help you create your best work . There are a lot of bad blog posts out there, and it's often not because the content is technically wrong - the code usually worked when the author created it — rather, bad blog posts suffer from: ❌ Having a poor structure ❌ Not adequately explaining prerequisites ❌ Not communicating why you should read it Instead, by following our guidelines below, you'll be able to write content that: ✅ Has a clear and logical structure ✅ Explains the pre-requisites necessary (and the context) ✅ Tells the reader "What You Will Learn" by the time they've finished the post There are 4 sections in this guide: Being remarkable starts with your mindset in how you approach your work. Here are the values we use to approach our work: Our blog posts should be detailed. In tutorial-based code posts, you should either: One of the most frustrating things for someone new is to read a post full of technical terms they don't know the post provides no explanation or context. Remarkable posts give you the missing context and explain every step. If detail is depth, comprehensive is breadth. One important way to be remarkable is for your post to be more comprehensive than any other page on the topic . Not every post has to be enormous, of course. But this is a straightforward way to be exceptional - you just have to be willing to put in the work. Part of our blog posts tell you how to do something, but we need to include why we do it. We'll talk about this more, but explaining the problem and context helps the reader understand the solution (and if it even applies to them). Teach how you'd actually do it at your job. Oftentimes blog posts advise readers on what they should or shouldn't do in a theoretical context, separate from any real-world concerns. Instead, we provide practical, real-world solutions: hacks and all. We're helping people meet their deadlines at work, build their startup, and get better jobs. Our advice should be practical and pragmatic. Being trustworthy as a post author means that our post is technically correct in the details. It also means that we discuss different options and tradeoffs. Being technically correct often means we update our work when things change. It also means that you should bring your unique experience into your writing through examples you've encountered through your work. Also, your name will appear on this post - so take the opportunity to create something you're proud to sign your name on. At a high-level, our process for writing a blog post is this: Other than writing the code, this should take only about 15 minutes, but it will make writing your post way easier because you'll have a solid outline to work from. This is straightforward: decide what you're going to write about. The typical way folks write an outline is they sit down at a blank page and start writing bullet points. This is fine if you have a clear picture of what you want to say. But oftentimes, we have only a vague idea of what we want to write — there are a few tools we can use to eliminate writer's block and write consistently great posts. Do the following: Time: 5 minutes Outcome: A bullet-list of questions Put yourself in the mindset of your reader and ask, "what are they looking for?" If someone is searching for the term "react hooks" and they click on your post, what are they hoping to find there? Use your list of questions as the foundation of your outline. Either pick one and focus on it or go broad by making sure you answer all of them. When you're reviewing your draft, you can look back over the list of questions and ask yourself, "did I answer this?" Time: 5-10 minutes Outcome: Bullet list of topics covered by other posts and a list of missing ideas Take a couple of minutes and search for other articles on your same topic. Jot down a master list of all of the topics they touch on. You need to decide the following: What Topics are Covered? If someone else has written about something, should you write about it too? It depends. My suggestion is default to "yes" . Many coding tutorials mention "key terms", but they explain them in a shallow or uninteresting way. You, on the other hand, are creating something remarkable, and your explanations are going to be clear, helpful, and correct. Just because someone else has written about a topic before does not mean you shouldn't . By using the guidelines in this document, you can probably teach the idea in a specific way that is uniquely valuable. What is Missing? Often when you do a bit of research on other folks who have written about a topic, the first impression is self-doubt. You might think, "Wow! This has been written about a lot. Maybe I'm just adding to the noise?" But if you actually dig into these tutorials with a student's eyes, you'll quickly see that 95% of them are a shallow rehashing of API docs. For most programming tutorials, the bar is pretty low. After you've: ... you'll start to see some holes Time: 5 minutes Outcome: A rough list of things you want to cover, in order At this point, you should have a document that lists several ideas you want to cover in your post. Put them in a logical order. We'll talk more about the overall post structure below, but this should give you a rough idea of the meat of your post. Time: 5-15 minutes Outcome: A list of code examples you're going to show In this step, decide the list of code examples you want to cover and write them down. Picking a good example is tricky: you want it to be complicated enough to teach the idea, but not so complicated that the student is lost in the weeds. Your code can come from three places: Try to provide a runnable code example (2 or 3) whenever possible. Also, for some ideas, you may want to provide a scaffold for the reader, which has all of the boilerplate setup work completed, and the reader simply needs to make changes in one small area of the code. The key component of writing a strong programming tutorial is: don't skip anything. But when you're writing the manuscript of your post, it's hard to remember all of the details that went into writing the code. So take notes as you're writing your code examples. Write down every little thing you did to get this code working. These notes become the basis for the article. Bad tutorial writers skip this part. And by the time they write their post, most of what they learned doesn't make it on paper. If you had to Google something, link to it. If you hit an error that you had to debug, include that error in your post and then explain your debugging process. If a library challenged your expectations, then tell the reader about it! Showing ways that you learned while building the app helps the reader far more than only giving them an answer they can copy and paste. As you're coding, take notes on questions you had, intuitions that were broken, and mental models you used to approach the process. Including these meta-level insights brings your post to remarkable. Because you're teaching more than code: you're teaching how to think about coding. There are two major kinds of posts on \newline: The Tutorial and the Tour. A \newline-style Tutorial teaches you how to do something in programming. A \newline-style Tour shows you a variety of examples around a theme. A Tutorial walks you through one (or more) example projects where you build steps 1 through n. A Tour walks through several examples, but they're not necessarily building on one another. In either case, the post has the following sections: We have an article template here that you can start with. Also, make sure you've read our formatting guidelines post here . Let's take a closer look at each of these sections. The title is the first thing someone will see about your post. You want to make it: Length : aim for between 8-15 words. Examples : ❌ react hooks ✅ React Hooks Tutorial for Beginners: Getting Started With React Hooks Compelling : Indicate to the reader what they're going to get out of the post in the headline Examples: ❌ Service Workers and Angular ✅ The Beginners Guide to Service Workers with Angular - A Step-by-step Tutorial ❌ Create React App 2.0 ✅ The Fullstack Guide to Create React App 2.0 - What's New and How To Use It Accurate : Use specific, concrete language to describe what's in your post Examples: ❌ Routing and you ✅ 10 Things to Consider When You're Choosing a Router For Your React App Some template ideas you can use for your title: Examples: ❌ React Testing Tips ✅ 14 React Testing Rules Every Great Programmer Should Follow Next step: Try drafting 3 or 4 titles and run them by someone else. The summary gives the reader a little bit more info on what they can expect from the post. It should be short - try to keep it under 280 characters — the length that could fit in a Tweet. Examples: You'll find that it's sometimes easier to write the summary after you've written then post. The introduction sets the stage and context for your post. Too often, blog posts drop you in the middle of a thought without orienting to where you are. A good introduction will set the stage for a reader. What are we talking about? When does this apply? Why do we even have a problem? A good approach to writing your introduction is to describe the problem. If, for example, you're trying to explain why someone should use a framework like React, then your introduction should explain the pain of trying to build a complex web application in plain JavaScript. Once you explain the pain of not using this, your reader is better prepared to understand your solution. The code you're trying to explain was written in response to a problem. So describe what life was like before this solution was created. "We used to do X, but it has problems A/B/C, so now we do Y." Then say, "in this post, we're going to show you how to do Y." Guidelines: Examples: Tutorial: Building Redux in TypeScript with Angular - Cites four specific pain points with the old way. This short section should directly tell the reader what they will learn by reading this post. Keep it factual and use bullets if you need them. Limit the length to 1 paragraph (or maybe 2). ❌ "In this post, you will learn about a GraphQL server." ✅ "By the end of this post, you will know how to create a basic GraphQL server in Node.js from scratch." Everyone comes from a different background, and when a reader first encounters a post, it can be hard for them to know if they understand the prereqs necessary to get value from it. While we want to create posts that are helpful for a wide audience, you can't rehash the history of computing and programming in every post - you have to pick a cutoff point. Use the prerequisites section to link to 2-4 URLs that come just before your article in the user's "journey". Think of knowledge like a graph and each blog post as a node on that graph. What are some edges that will connect your blog post naturally to a few prerequisite topics? Include those prereqs as URLs and, if necessary, give a sentence on each one. When possible, link to resources within \newline - this way the community's knowledge can build upon each other. ❌ "Unless you've been living under a rock, you probably know what Redux is by now." ✅ "This article explains Redux which is an intermediate data architecture pattern for React and other web frameworks. If you're just getting started in web development, you should check out these articles first: These sections are where you will walk through the tutorial and explain every step to the reader. It's the meat of the article. You open the article by defining your code starting point. This could be an empty folder, a Codepen, a code starter kit, etc. Give them a link to the Github repo, Codesandbox if you have one. Whatever it is, make it clear to the reader where we're starting. Then iteratively add conceptual chunks of code and teach each concept as you build the final example. My biggest suggestion is that break up your explanations and show no more than 20 lines of code at once . Using \newline's embedded code blocks makes this easy. Show some code. Talk about it. Show a little more code. Talk about it. A tour of features is structured differently than a coding tutorial in that the examples typically don't build on each other. For example, a guide to the various React hooks might take four hooks ( useState , useEffect , useContext , useRef ) and then give one code example for each. But beyond that, the approach is very similar to a coding tutorial: show a code example and explain it in detail. Again, take the time to explain each example thoroughly. Examples: At the end of your post summarize what you've talked about. Remind the reader why it's valuable and what it means for the future. This is also your chance to give a call-to-action, if you have one. Close your article by listing resources where someone can go next to learn more. If you used any other sources in your research, give credit and link to them. Give the reader clear steps for where they can learn more. Formatting is an important part of creating a readable post. Go read this newline blog post on formatting . You can start your article by copying and pasting one of the following templates: I've found the following resources to be valuable in learning how to teach. I highly recommend reviewing the following links when you have time: Hop over to the newline write page , copy and paste the newline Tutorial Template , After you've written your post, take a look at the newline Blog Post Checklist . If your post checks every box there, then you're good to go. Share your article with the world! If you have any questions - or want feedback on your post - come join our community Discord . See you there!
