Did you create a great new tool? Solve a problem you weren’t sure could be solved? Build a demo app you want to share? People want to know about it - but unfortunately, they have very short attention spans.

This guide is intended to help you create detailed technical stories, including code snippets, architecture diagrams, etc. It might seem odd to think of detailed technical guides as “stories”, but if you want readers to follow your process, you need to have a plot with a beginning, middle and end, and you need to keep readers engaged in your narrative by making it relevant to them.

(A quick note: Have you ever read a story that seems to just be a pretext for the author to rant? Not much plot, boring characters, and lots of diatribes? Don’t be that writer! Save your ‘hot takes’ for later. This guide is for the HOW, not the WHY.)

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

A few examples of “How I Built It” articles - what works for you as a reader and learner?

• 6 Steps to Migrating Your Machine Learning Project to the Cloud
• Build Your Own Livestreaming App with Twilio Live
• Build a React Search App with Algolia Indexes for Fast Inventory Updates

Start With Framing Questions

• What is the problem you set out to solve? How did you uncover this problem? What were your initial feelings about tackling it?
• What are the steps you took to solve this problem? Which turned out to be necessary, and which paths did you abandon?
• What obstacles did you come across? Were any of them unexpected? How did you get around them? Include meaningful code snippets or diagrams so others can follow.
• What did you learn from this project? What was the outcome? Are you still evaluating? Are there any next steps? What recommendations do you have for others?

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.

Set a Manageable Scope

A good short story has a limited setting and a focused plot! How can you bring clarity to the most important events or conflicts in your technical story?

• What should readers understand when they finish? Is it your goal for them to be able to build the same project you did, or to understand the journey you went through?
  • Is your goal to educate about specific technical tools? Focus on what worked.
  • Is your goal to share strategies that helped in your journey? Show how you failed forward.
• What background knowledge does your reader need? What do you want to explain? Provide links for other important concepts.
• What aspects of the project can you explain in general terms? Leave out technical details that don’t directly affect your main “plot”.
• If you need to discuss multiple levels of your tech stack in detail, what is the clearest approach?
  • One layer at a time – Will you fully explain one layer at a time, with explanation of how they connect at the end? This might work best for describing a project where your backend data dictated everything else.
  • All layers in parallel - Will you through the project chronologically, addressing each element at each stage? This might be a good fit for explaining the evolution of a consumer-facing app that you adjusted based on user feedback.

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, taken from my days as an English teacher - in some future post, maybe I'll lay out some article ideas using these templates to show how I might use them:

• The good old idea web!
• An actual plot diagram - Build in a little suspense, show how conflict made the end result better.
• A problem-driven organizer - The best technical stories center on a person who needs something.

A Classic Outline Template:

Problem-focused Headline w/ brief mention of solution

Subheading to introduce real-world scenario

• Introduction
  • What problem are you addressing?
  • What are the technical requirements and business requirements that provide the context for the problem? Help readers understand your limitations & motivations.
• First step in your process (Use an active verb like “Install” or “Initialize” to help readers see what their first step would be.)
  • Overview of the project structure & link to important background info
  • Screenshots or code snippets to show proper setup
• Second step (Include a reason! “Do X to Allow Y” or “Choose A if You Need B”)
  • Caveats and double-checks. Did you have any false starts?
  • How will someone following this process know it’s working properly?
• Third step (3-6 total steps is a good target for detail & approachability)
  • Code snippet or screenshot showing important details
  • Explanation of how components function together
• Conclusion subheading that implies a next step
  • Current or future projects where you might apply what you learned
  • Who else might want to try this approach and on what type of project?
  • Where should people go to learn more?

Sample Outline For Personal Python Project:

Install Python 3 to Build Quick Custom Apps For Your Life

How I Manage My Finances with Jupyter

• Intro
  • My conundrum: Managing my finances! My solution: 2 birds with 1 stone!
  • What is Python? Used a lot for math & finance, provide some links
  • Allegedly easy to learn & use
• Check For Python on Your Machine
  • I thought I didn’t have Python! Avoid my mistake of making a mess with 2 installs!
  • Where to find the right Python for your OS - provide links & screenshots
  • Include Python in Your Path - What is a ‘path’? Provide a link?
  • Screenshots & CLI code snippet
• Run Your First Python 3 Code Faster With Jupyter Notebook
  • I assumed I’d be working in the browser! Imagine my delight!
  • “Hello World!” code for Jupyter
• Make The Fastest Custom Data Viz Ever
  • Install a couple of tools
  • Make A+ personal finance charts with C+ effort!
• Build Your Next Life-Hack Project with Python 3
  • Resources for learning more about Python
  • Ideas for other life tasks to make easier with Python/Jupyter
  • Encouraging words for new Python developers!

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.

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?
• Are your code samples explained?
• Do your links work?
• Do your headings make sense?

Sitting on your draft for a day or two gives you some time to reflect and let ideas percolate. Even better, 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!