We’ve all heard enough “hot takes” to boil a pot of water, but opinions that are expressed memorably and compellingly are a much rarer commodity. If you think you have a perspective people should hear, a purposeful approach is going to get you more buy-in than a spontaneous flood of tweets.

This guide is to help you write articles that explain WHY you recommend a particular technical approach. You don’t need extensive code samples. The goal is not for readers to be able to reproduce a specific feature, but to be able to make more informed choices in their future work. Get as concrete and specific as you can about the work you’ve done that shaped your thinking. Dig into pros and cons of different options you’ve considered and explain the logic behind your opinions.

In terms of Aristotle's rhetorics, i.e., the art of persuasion, you need to build some ethos. Establish your credibility on this subject in ways that will appeal to readers. Many writers focus on logos, or logical appeals. Obviously, you need to share reasons behind your opinions, but avoid the temptation to “out-logic” the other side. We all know there’s rarely a single correct technical solution to a problem, but it can be hard to sort out high quality advice. Your unique perspective and experience are the most valuable resources you have. Don’t be arrogant, but show readers why they should pay attention to your voice.

Overview

1. Give your idea shape with examples and framing questions
2. Plot the path ahead - brainstorm and outline
3. Fill in the details of your unique story
4. Seek feedback and revise
5. Publish on your blog or other site

1. Define and Shape Your Idea

Get Inspired By A Few Good Examples

Consider what works for you as a reader and learner in these examples:

• Why I choose Next.js and Sanity for my new blog
• Aligning Your API Design Using Jobs-To-Be-Done
• Intro to GraphQL (This is actually a "Why GraphQL" article)

Start With Framing Questions

• What is the problem you are focused on? What human-centered use case illustrates the problem?
• Who are you talking to? How is your advice going to make their lives better?
• What background knowledge does a reader need to understand your main idea?
• What background knowledge and experience do you have that shaped your conclusion?
• What are the alternatives? Did you try them? Why didn’t they work? Or why did you not even try?
• What are the drawbacks of the approach you’re recommending?
• Did you change your mind about any aspect of this problem and/or solution? Or did things go exactly as you expected?
• How certain are you about your conclusions? What would make you change your mind?
• Who else would benefit from taking your advice? What kind of projects?
• How will you put your principles to the test in the future? What else do you need to investigate?

2. Plan Ahead to Tell A Clearer Story

Your high school English teacher was right — a little preparation can make your writing process a lot more successful. The effort you invest in an outline pays off when it’s time to write the article, especially if you won’t be writing your entire draft in one sitting.

Learn From Debaters

Let’s assume you’re already planning to provide evidence for your arguments. Take it a step further and make it relevant to your readers with a model used by debaters. You have a thesis – your main idea, your central opinion, however you’d like to frame it. You probably have a few reasons to back it up. We’ll call those “Claims”. For each Claim, you should also provide a “Warrant” and an “Impact”.

• **Claim: **An opinion-based, falsifiable statement that supports your main idea.
• **Warrant: **Factual information that supports your claim.
• **Impact: **The material consequence of your Claim, in terms of your intended audience.

For example, maybe you are trying to convince your readers to stop using React Native. One of your main supporting reasons might be that it’s not _actually _native code, but still requires knowledge of native development. That’s your claim. **A **warrant would be an example of a real-life project built in React Native that did not work on both Android and iOS without additional device-specific code. The impact for your readers is on their workload and support costs, either as individuals or development teams.

Organize Your Ideas For Your Own Benefit

There’s no one secret formula for outlines. A process that works for you is the winner, but it may take experimentation to find it. Try different approaches, iterate, and keep moving forward! A few ideas:

• The good old idea web!
• A Venn diagram with your preferred option & one or two alternatives
• Pro/con chart
• Compare/Contrast organizers

As you generate ideas, pick 2-4 ideas to focus on and develop with supporting details. Look for overlap between different reasons - like “productivity improvements” or “accessibility” that can incorporate multiple supporting examples.

A Classic Outline Template:

Problem-focused headline w/ brief mention of your preferred solution

• Curiosity-inspiring opinion about a relatable problem
• First reason your solution is a good one (Active verb to highlight a benefit)
  • An alternative solution that didn't achieve this goal
  • Why your chosen solution works better
• Second reason…
  • Why your solution wasn't perfect at first
  • How you adapted
• Third reason… (Ideal is 3-4 total paragraphs describing your choices.)
  • What worked exactly as you hoped?
  • Unexpected benefits you discovered
• Conclusion suggesting next steps
  • Current or future projects where you might apply what you learned
  • Who else might want to try this approach? What kind of projects?
  • Where should people go to learn more?

Sample Outline

How I Kept My OSS Project Moving With Flutter

• Mobile development is hard, and so is working with people! Flutter made both easier.
• Constraints are good for collaboration
  • People thought Flutter would be more limiting than React Native
  • The limits don't mean you'll make a worse end product
  • Getting people on the same page is easier when there are clear external guidelines
• Flutter Just Works
  • React Native required so much "fixing", it generated tons of GitHub issues
    • Flutter takes more effort up front, but once it's done, it runs predictably everywhere
• Learning Dart & Flutter is attractive to people
  • A lot of devs were enthusiastic about opportunity to learn the hot new thing
  • It attracted a lot of experienced people to the project who weren't that excited about more React Native
  • Combo of declarative UI and OOD backend means opportunities for people with different interests
• You should convert your OSS project to Flutter. Once we've built more, maybe I'll give a talk about how we did it.

3. Write Naturally! It’s YOUR Story!

Don’t sweat the details when it comes to grammar, writing style, or perfectly formatted screenshots. The most important thing you can contribute is your unique understanding of the problem space you’re working in. Write in a voice and style that are comfortable for you, and err on the side of including more technical detail than necessary - you can always pare back later.

Be A Humble Authority

Everything has tradeoffs, and everyone has blind spots. Acknowledge them! Be confident in what you know and the experiences you’ve had - but remember that confidence reveals itself in a willingness to be wrong and consider other options. Readers are far more likely to trust you and finish reading your article if they see you as an open-minded, thoughtful person than if they see you as arrogant and inflexible.

Consider a Few Tips

• Most readers like casual style, concrete examples, and short sentences and paragraphs.
• Active verbs and opinionated headings spur readers’ creativity and analytical thinking.
• Links to high-quality background resources are great - don’t try to do it all yourself.
• Plain language makes content accessible. If you need jargon and acronyms, explain!
• Code samples should be formatted with markup or otherwise separated from the explanatory text - make them usable for others!

Inspire Readers With Final Thoughts

Don’t skip the conclusion! The value in sharing your experience and insights is in how it can spur learning and creativity for others. Take a few sentences to reflect on the problem, your solution, and what you learned along the way. You don’t have to be certain about any of it—it’s just fine to leave some open questions, but offer some thoughts on how you or someone else might answer those questions in the future.

4. Reflect, Share and Revise

When you’ve finished writing, don’t click ‘publish’ right away. You put a lot of effort into this - it’s worth taking a bit of extra time to polish it up a little.

Read your conclusion, then circle back to your introduction. Do they make sense together? If you provided an outline in your introduction, does it reflect what you actually wrote?

Look back over your body paragraphs. Are your code samples explained? Do your links work? Do your headings make sense?

Even if you don’t do that kind of analytical revision, sitting on your draft for a day or two gives you some time to reflect and let ideas percolate. It’s also an opportunity to share with some trusted readers. Ask a couple of other people to read your draft and provide feedback. You don’t have to change anything, but give yourself the opportunity!

5. Publish & Promote Your Heart Out

The final step, obviously, is to publish and publicize. Where is up to you, but be proud of what you’ve done and show it off – just the fact that you did it sets you apart from the crowd. You’ve shown an admirable commitment to your own growth and to your community, and we want the chance to cheer for you!