A Technical How-to vs. a Technical Tutorial

Technical tutorials give a lot more background and information, and may incorporate how-to’s within a broader context that gives much more detail about why, what, and how. Technical how-to’s more narrowly focus on completing a specific task with a specific tool, platform, or technique. Developers with more experience may find how-to’s more useful, whereas those new to their careers may find tutorials more useful as they are still obtaining more general knowledge about their field. When Evans Data Corporation asked developers about the technical content topics they were most interested in — for the Developer Marketing Survey 2019 — among the 45% of developers who said they were most interested in tips and tricks, there was a slightly higher incidence of developers who were also most interested in how-tos.

Best Practices

Developers are people, and their learning styles and preferences vary as much as anything does among us humans. However, some things are held in common. So whether you’re striving to appeal to Boomers or Gen Z, you are bound to attract your audience if you keep these things in mind.

Include Text with Videos

Videos are very popular for developer audiences across many roles and ages.  In fact, according to Evans Data Corporation, developers who responded to the 2019 survey said they were likely to watch videos in order to develop their skills. They also prefer the video format over webinars or white papers to learn about specific use cases. (Sounds like they may be a good choice for how-to’s.)

Except…

  • Videos are hard to search to find content
  • Code is difficult to copy from video

But don’t abandon videos! They are just too popular. The solution is to couple videos with text. Provide a transcript, for instance, and your content at least becomes searchable by a simple CONTROL F.

While captions and a transcript can be helpful, you might go a step further. Consider pairing your video content with a how-to article that holds to the principles that follow.

Text Content that is Visually Scannable

We have heard from a LOT of developers in our Ask a Developer video series, and when we ask developers about what makes content developer-friendly, they converge around the importance of having written content that is visually scannable or quickly scannable.

Start High Level, Then Go Deep

Developers surveyed by Evans Data Corporation vastly prefer technical content that has high-level topics offering links to deep dives over content that starts directly with all the details.

Use Straightforward Language

Developers like Miko Charbonneau and Erik Guzman respond better to simple language that assumes a beginner status, and then walks the reader up to a higher level.

Don’t Make Them Download

Offer code samples that the reader can copy and paste if they are short, but for something lengthy, consider offering an online code editor and repo right there in the article for them to try.

Have a Little Empathy

Regardless of age, developers are busy and highly motivated to solve problems. Organize your how-to’s so it is easy for a beginner who found your valuable content to implement it right away. Don’t make them view an entire video to find the answer they need. Include video, text, images, and code samples, but make them easy to visually scan and search — and where needed, let them try the code.