Writing Docs With Code Samples? Try Out the New Writerside EAP Release

Each Early Access release is designed to make writing documentation easier and more enjoyable. This update is based on your feedback and focuses on improving code blocks, but there is more! Thank you all for sharing your ideas. It’s a pleasure to keep improving our product for you.

Code samples in documentation: Stick to the basics

When I first started thinking about presenting code samples in technical documentation, the initial idea was about advanced features, like interactivity, robust linking between text and code, and sophisticated presentation options, such as substituting placeholders on the fly. 

However, the recent Unconference session at the Write The Docs Atlantic conference revealed something surprising – the most pressing concerns regarding code blocks weren’t about cutting-edge features, but about getting the fundamentals right.

Reality check: Know your audience

At the conference, the discussion quickly shifted from “How can we make our code samples more interactive?” to “What does our audience actually need?” This pivot highlighted a fundamental truth in technical writing: understanding your readers’ goals is more important than implementing cutting-edge features.

The 4 key insights regarding code blocks

1. Context and purpose

It’s not about “short” versus “long” code samples – what matters is context and purpose. Tutorials need complete, real-world examples. API docs benefit from focused code blocks that demonstrate specific functionality. 

2. Copy-paste is the reality 

There’s no way around it – regardless of experience level, people consistently copy and paste code samples. We can’t fight it, but we can use code blocks that are complete enough to work even when directly copy-pasted, or that indicate what to do to make them work. 

As Chris Chinchilla points out in “Technical Writing for Software Development”, developers frequently copy and paste a series of code snippets into an editor because it’s a fundamental part of learning.

3. Different strokes for different folks

Code samples serve as learning material, and, like any other learning resource, one size does not fit all – different learning styles call for different examples. Beginners might need step-by-step breakdowns, while expert developers might prefer more comprehensive examples that they can tweak to fit their own needs without much hassle.

4. Complementary tools

Swagger specs and Postman collections are great companions to documentation, but not replacements. They help users move from learning to doing, once the concepts are clear.

Code block maintenance: The hidden challenge

As products evolve, keeping code samples up to date is crucial – and challenging.

• How can you efficiently update examples across documentation?
• When should you remove or deprecate outdated examples?
• What are the best strategies for version management?

These challenges aren’t new to us at JetBrains. We’ve explored several automation strategies in our previous post about keeping documentation up to date. Building on those insights, we’re now focusing on code sample maintenance.

Chris Chinchilla, in his recent book, outlines two approaches to documentation testing:

• Manual testing: Writers regularly verify examples from a newcomer’s perspective.
• Automated testing: Tests are integrated into CI/CD pipelines for continuous verification.

Another approach, called Docs as Tests, is being actively explored by Manny Silva. We highly recommend checking out both Chris’s book and Manny’s project for further inspiration.

As we continue to evolve Writerside’s code sample capabilities, we’re keeping this lesson in mind: the best features aren’t always the flashiest – they’re the ones that help writers meet their readers’ needs, whoever those readers may be.

New in Writerside EAP 9: Code block enhancements

The latest Writerside release focuses on practical improvements that directly address common challenges with code blocks:

External code block references provides a single source of truth for code samples, reducing maintenance overhead.

Enhanced language support ensures accurate syntax highlighting across more programming languages.

Native support for .puml and .mermaid files streamlines the integration of diagrams with code samples.

Working with code samples? Help us stay up to date

We’ve learned that the best documentation improvements come from understanding real-world needs. Have you faced challenges with code samples in documentation? Which features make a difference in your daily work?

Whether you’re a technical writer crafting examples or a software developer, we’d love to hear your perspective. Join the conversation in our Slack community and help shape the future of code samples in Writerside.

But wait, there are more features and improvements!

Writerside EAP 9 offers more than just improved code blocks:

• PDF CLI: Our builder can now produce PDFs alongside the web output.
• The Good Docs integration: We’ve improved our recent integration of The Good Docs project templates.
• API documentation generation: You can now generate API docs as a new instance.
• Table of contents: This long-awaited feature provides a table of contents for topics with API docs.
• Multi-specification support: Generate documentation from multiple specification files.

👉 Read the full release notes

We hope you like the new features. If you have feedback or ideas on how to make Writerside better, we’d love to hear from you!