This content originally appeared on DEV Community and was authored by Jeff Morhous
If you're looking to improve technical content on your site, one of the first things you should do is refresh your older programming tutorials. There's little ROI in making new programming tutorials if all of the traffic to your existing articles is unsatisfied with what they find.
In this article, we'll first talk about why you should refresh your programming tutorials. Then, we'll dive into how to get the greatest return on your time when refreshing these tutorials. We'll cover updating screenshots, updating library and language versions, and updating links.
We'll also dig into what it takes to make sure your tutorial is incredible, and we'll touch on SEO optimization for tutorials as well. By the end of this guide, you should be confident that the effort you invest into bringing your tutorials up to date is well-spent.
Why You Should Refresh Your Programming Tutorials
Periodically refreshing older programming tutorials on your site helps you get the most value out of the assets you already have. You've already put the time or money into creating detailed educational content for developers, so it makes sense to put in the work to maintain its integrity.
You wouldn't plant a garden and never tend to it. You shouldn't publish technical content and expect it to stay fresh over time. Technology moves fast, and things get out of date quickly. Publishing the best tutorial on a programming topic is a huge win for a business, but it's also a moving target.
Outdated tutorials cause developers to lose trust in your brand. One of the biggest goals of publishing technical content is establishing your brand as a trusted voice in the developer community. Going through old content with regularity helps you put your best foot forward.
To put it concisely, here are the biggest reasons that programming tutorials need to be refreshed periodically:
- Languages get updates that may break tutorial instructions
- Frameworks get updates that may break tutorial instructions
- Tools often change, making screenshots out of date
- Outdated tutorials leave a bad impression on visitors
- Outdated tutorials increase bounce rates, which hurts SEO
In the rest of the article, we'll show you concrete steps to take when editing technical content.
Updating Language and Library Versions
Your tutorials took time to write, and they take time to maintain too. If a developer begins a tutorial and sees an outdated version of React, they're likely to bounce back to Google, which hurts your trust and SEO.
Every hands-on programming tutorial instructs the reader to do something in a language of choice. Over time, the syntax of a given programming language changes. While language design changes often don't break existing code, using an old language version is a common sign to a developer that a tutorial is outdated, leading them to wonder if the tutorial is still valid. Some language updates, like Python 2 to Python 3, are large enough changes to require changes to the way tutorials are written.
Even more common than language updates are framework and library updates. While JavaScript might not change often, popular libraries like React frequently change in ways that make tutorials useless. Using an outdated version of React in a tutorial is fine only if the reader is also using the outdated language version. Readers want to solve the problem they're searching for help on with the tools they're already using, so keeping tutorials up to date with the latest library or framework updates is important!
Programming tutorials should always list software versions that the tutorial assumes the reader is using at the beginning of the article so that the reader knows what assumptions the writer has. This makes versions easy to audit as part of a tutorial refresh. The editor that is refreshing a tutorial should check the versions of languages and frameworks being used in a tutorial against the current versions and make any upgrades necessary to bring the tutorial up to date.
Updating Screenshots
Another important part of tutorials to keep up to date are the screenshots. High-quality screenshots help readers know they're on the right track, so outdated screenshots can be confusing or even frustrating.
Screenshots are also one of the best ways to stand out from AI-generated content, as LLMs aren't able to generate screenshots alongside their instructions. Programmers who are having no luck solving their problem with an AI tool should be delighted by the screenshots in your tutorial.
Great screenshots should:
- Be high resolution
- Contain only easy-to-read text
- Not contain sensitive information like API keys
- Be cropped appropriately
- Be up to date with the latest changes to project/framework/dependencies
Updating screenshots is an absolute must when refreshing programming tutorials. It's the most loved part of our technical editing service, where we have a practicing software engineer go through a tutorial and complete it as part of the editing process.
Updating Links
The next crucial part of updating tutorials is to update links. This applies to any article but is especially crucial for technical content. It's also especially important for internal links, as this helps Google understand your site structure and page relationships.
As you go through an article to edit it, click every link to ensure that it's still valid. URLs change over time, and links go stale. Beyond ensuring that links go somewhere, ensure that the anchor text of the link tells an accurate story about where the link will take the visitor.
Links should have descriptive anchor text that tells the reader what to expect if they click. Here's an example of bad anchor text:
For more information, see the Python documentation here
Here's an example of better anchor text:
For more information, see the Python documentation
For an even better link, you should make sure that the page you link to is a great source of information, and specific enough to be quickly helpful. The above example could be further enhanced to:
For more information, see the Python documentation on integer literals.
As you go through and update links, take the opportunity to note any links that might make for good resources on your own site. This is often called the wiki strategy, where you make sure the reader has all the information they need on your own site. It's a great way to come up with relevant new content ideas and increases the time visitors spend on your site.
Optimizing for a Great Tutorial
The most immediately obvious part of refreshing a tutorial is to make sure it's a great tutorial. Ideally, you've done this as part of your writing and review process, but the extra time between writing and editing makes it easier to spot things that aren't clear.
The best way to make sure a programming tutorial is great is to actually do the tutorial. If the article is thought leadership, this section doesn't apply. But for practical, hands-on tutorials that instruct the reader to do something, it's important to have a practicing software engineer go through the article and follow the instructions exactly. This will illuminate anything outdated or broken, as well as provide opportunities for clarifying instructions and updating screenshots.
Great programming tutorials should be sure to:
- Contain a good introduction that describes what the reader will learn
- List all prerequisites with links to instructions
- Use consistent voice and style
- Have code blocks with proper language annotation
- Contain only code samples that follow a language's best practices
- Contain only code samples that have consistent spacing
- Contain only code samples that follow best practices for a language (like passing a popular linting tool)
- Be easy to follow given the reader has the prerequisite knowledge
- Show the reader how to do the thing promised in the introduction
Be sure to follow your article top-to-bottom, just like a reader would. As you complete the instructions, follow this checklist to find and fix issues that you find.
Optimizing for SEO
One of the biggest goals of technical content marketing is to bring traffic from organic search to your site. If your articles aren't optimized for search, your efforts could be wasted.
Fortunately, the most important SEO virtue is trust. When readers trust your content, Google picks up on these signals and increases your rankings. The most important SEO optimization you can make for an article is to put all that you can into making it the most valuable article for a given topic. Ensuring that your content is of the highest quality provides incredible value for readers, which necessarily hints to Google that your content is valuable to other searchers.
Beyond just making sure you have great content, there are a few things to keep in mind for SEO when updating tutorials. First, you should use descriptive H2 headers to separate sections of content in articles. These H2 headings should contain long-tail keywords you're trying to rank for and will be a strong signal to Google what queries your content should rank for.
Second, your article should be easy to parse for a reader. H2 headings are helpful for this, but so is avoiding huge walls of text, including images, using bullet points, and leveraging tables. These changes make content scannable, which keeps readers engaged and signals to Google that your content is a good resource for the searcher.
Lastly, your article should contain internal (descriptive) links where appropriate. If you're mentioning a topic that you've covered on your site, link to that resource with descriptive anchor text. This ensures the reader can get the information they need without leaving your site, which is a good signal for search engines. It also helps Google understand the relationship between pages, and high-ranking pages may pass page-rank authority to the lower-ranking pages to which they link.
Conclusion
Refreshing your programming tutorials is not just about keeping up with technology—it's about maintaining trust with your audience and maximizing the ROI of your content. By updating language versions, refreshing screenshots, and ensuring all links are current, you not only improve user experience but also boost SEO performance.
At SyntaxPen, we specialize in helping businesses build libraries of technical content that build their brand as a trusted voice in the developer community. Whether through our comprehensive technical editing service or one ofour full-service options, we're here to ensure your tutorials remain valuable and trusted resources in the developer community.
This post was originally written on the SyntaxPen blog
This content originally appeared on DEV Community and was authored by Jeff Morhous
Jeff Morhous | Sciencx (2024-07-16T02:56:31+00:00) The Ultimate Guide to Refreshing Programming Tutorials. Retrieved from https://www.scien.cx/2024/07/16/the-ultimate-guide-to-refreshing-programming-tutorials/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.