Coder Legion - Recent posts tagged technicalwriting

"How I shortlisted my Organization at GSoC '26"

Sun, 28 Jun 2026 23:13:21 +0000

I opened the GSoC organizations list halfway through in March 2026, incredibly late, I knew I was only a fortnight away from the GSoC application deadline and hadn't picked an organization yet.

My constraints were simple: Python-heavy, less crowd, and alive and responsive maintainers.
Scrolling down I looked for small orgs some of which were under other umbrella organizations and came across some orgs that met my needs.
-Wagtail looked almost perfect but their AI policy was strict and the competition was high, figured I would be wasting time especially after getting in late already.
-Alpha One Labs under OSL sounded approachable until I read their actual project ideas, every single one involved deep ML research or computer vision systems. Wasn't my territory.

Even went after the famous ones like Numpy but had to rule them out because the projects tend to require strong numerical computing background and they were crowded also.
After consulting with my friendly neighbor claude, I got some real good suggestions, one of which was Mailman.
All I had to do was check the issue publishing rate, the activity of my mentors and other fellow contributors, and the competition here just felt right. Their GitLab was actively maintained and maintainers responded within days, sometimes even in few hours.

They had one hard requirement: a merged MR before submitting a proposal. This was a nervous but definitely the best opportunity I could come across.
I managed to get two MRs merged (about which I will write separately).

The project that fit me best after my MRs was Per-List Backup and Restore something that the mentors saw as a real gap in the software that affected real administrators.

(Per-List Backup and Restore was a project that was listed by the organization only)

and that is how, I picked Mailman.

Navya,

checkout my gitlab!
[https://gitlab.com/Naveeeya]

Physical Keyboard for Typing Math

Sun, 07 Jun 2026 18:55:16 +0000

I built a compact physical keyboard for people who type mathematical and scientific symbols often.

The idea came from a small but repeated frustration: writing math by hand is fast, but typing math on a computer usually means stopping to find the right symbol.

If I need a scientific symbol while writing notes, slides, lab reports, or technical explanations, I do not always want to open a symbol menu, copy from an old document, or switch into a full equation editor.

So I started working on the Nitrax Mathematical Keyboard.

It is a physical math keyboard, not a virtual keyboard, calculator, or generic keypad. The symbols are printed directly on the keys, with blue and gray symbol layers accessed through key combinations.

On Windows, the companion app uses AutoHotkey to send Unicode characters into the active application when Math Mode is enabled.

The goal is not to replace LaTeX or professional equation typesetting. It is for everyday math typing in normal writing workflows, where you just need the symbol now and want to keep writing.

Project link: https://mathematicalkeyboard.com/

I would be interested to hear how other developers would approach the layout problem: would you organize math symbols by category, frequency of use, or memory cues?

The Fastest Way to Lose Users Is to Make Them Feel Stupid

Mon, 18 May 2026 12:53:59 +0000

One thing I’ve noticed working around developer products:

Users can forgive bugs.
They can forgive missing features.

But they rarely forgive confusion.

Especially the kind of confusion that makes them feel like they’re the problem.

The Mistake Most Teams Don’t Notice

A lot of products explain things like this:

“Simply configure…”
“Just connect…”
“Obviously, you’ll need to…”

Those words seem harmless.

But to a new user, they create pressure.

Because when something doesn’t feel “simple,” the user starts thinking:

“Maybe I’m missing something.”
“Maybe I’m not technical enough.”

And once users feel that way, they stop exploring confidently.

Good Documentation Does Something Bigger Than Explain

It reassures.

It guides.

It makes users feel capable.

That’s why the best onboarding experiences don’t just teach users what to do…

They help users feel smart while doing it.

What I Focus On When Improving Documentation

I usually look for moments where users might pause and think:

“Wait… what does this mean?”

Those small moments matter more than teams realize.

Because confusion compounds quickly.

One unclear step becomes hesitation.
Hesitation becomes frustration.
Frustration becomes abandonment.

A Small Change That Makes a Huge Difference

Instead of writing:

“Simply authenticate using your token.”

You can write:

“Paste your API token here to connect your account. Once connected, you’ll be able to make your first request.”

Same action.

Completely different experience.

One assumes knowledge.

The other guides the user.

The Truth Most Teams Learn Late

Users don’t leave because they’re not smart enough.

They leave because the product made them work too hard to understand it.

Final Thought

A good product solves problems.

A great onboarding experience removes intimidation.

If users are struggling to get started with your product, API, or platform…

That’s usually the gap I help teams close.

I Looked at the Best Programming Blogs for Python Developers — Here’s What Actually Stands Out

Tue, 05 May 2026 05:46:29 +0000

There’s no shortage of Python content online. The problem isn’t finding blogs. It’s figuring out which ones are actually worth following over time.

Some sites are great for deep tutorials but don’t update often. Others publish frequently but vary in quality. A few manage to strike a balance, and those are usually the ones developers keep coming back to.

While going through different programming blogs for Python developers, one thing became clear:

Not all “Python blogs” serve the same purpose. Some are standalone learning resources. Others are part of larger developer platforms that publish Python content alongside other topics.

If you’re trying to decide what to follow in 2026, it helps to look at both.

Quick Answer

Some of the best programming blogs for Python developers include In Plain English (and Python in Plain English), Real Python, DEV Community, Stackademic, Talk Python, PyImageSearch, and Hashnode.

In Plain English stands out for its combination of consistent publishing and a dedicated Python publication
Real Python is one of the most reliable sources for in-depth tutorials
DEV Community is useful for practical, real-world Python content
Stackademic offers structured, educational articles
Talk Python helps you stay connected to the broader Python ecosystem
PyImageSearch is excellent for niche topics like computer vision
Hashnode brings together independent developer blogs

Each of these is useful for a slightly different reason.

What Makes a Python Blog Worth Following?

When you’re not just reading occasionally but actually following a blog, a few things start to matter more:

Consistency:
Does it publish regularly enough to stay relevant?
Clarity:
Are concepts explained in a way that’s easy to follow?
Depth:
Does it go beyond surface-level explanations?
Relevance:
Does it reflect what developers are actually building?
Usefulness over time:
Is it something you’ll keep coming back to?

The blogs below stood out because they perform well across at least some of these areas.

Best Programming Blogs for Python Developers (Curated List)

Blog / Platform	Best For	Content Style	Why It Stands Out
In Plain English	Consistent Python content + distribution	Accessible tutorials	Combines ecosystem + dedicated Python publication
Real Python	Deep learning	Structured tutorials	High-quality, in-depth content
DEV Community (Python)	Practical insights	Community-driven	Real-world use cases and discussions
Stackademic	Structured learning	Educational guides	Clear progression and explanations
Talk Python	Ecosystem awareness	Blog + podcast	Industry trends and updates
PyImageSearch	Niche depth	Specialized tutorials	Strong focus on computer vision
Hashnode (Python blogs)	Diverse perspectives	Independent blogs	Wide range of voices

1. In Plain English — A Consistent Python Content Ecosystem (Plus a Dedicated Python Blog)

If you’re looking for something to follow consistently, In Plain English is one of the more dependable options.

What makes it different is that it operates as a broader developer content ecosystem rather than a single blog.

On one level, it publishes Python-related articles directly on its main platform. These include:

tutorials
practical guides
tooling and framework walkthroughs

Alongside that, it also runs a dedicated publication: Python in Plain English.

That combination matters more than it might seem.

the main platform gives you broader exposure to Python alongside adjacent topics like AI and cloud
the Python-focused publication gives you a more concentrated stream of Python-specific content

In practice, this means you can:

follow only Python-focused articles
or stay connected to how Python fits into the wider development ecosystem

Another thing that stands out is consistency.

Because content comes from a large contributor base, there is a steady flow of new articles. That makes it easier to keep up with:

new libraries and tools
practical implementation ideas
evolving best practices

Compared to standalone Python blogs, it feels less like checking in occasionally and more like having a continuous stream of relevant content.

That mix of frequency, accessibility, and topic coverage is what puts it at the top.

2. Real Python — Still the Gold Standard for In-Depth Learning

If there’s one name that shows up in almost every list of Python blogs, it’s Real Python.

And for good reason.

This is one of the few platforms that consistently delivers:

detailed tutorials
structured learning paths
well-explained concepts

The difference is noticeable when you read through their content.

articles are carefully organized
examples are clear and practical
explanations go beyond just showing code

It’s especially useful when:

you’re learning something new
you want to understand a concept properly
you need a reliable reference

Compared to higher-frequency platforms, Real Python publishes less often, but the depth tends to make up for it.

3. DEV Community (Python Tag) — Practical, Real-World Python Content

DEV Community works differently from most traditional blogs.

It’s not a single editorial voice. It’s a platform where developers share what they’re working on.

That changes the kind of content you get.

quick tutorials
debugging experiences
lessons learned from real projects
comparisons between tools and approaches

If you’re trying to understand how Python is being used in practice, this is one of the better places to look.

Compared to more curated blogs, DEV Community is more immediate.

content reflects current problems
discussions add extra context
feedback helps refine ideas

It’s particularly useful for staying grounded in real-world use cases.

4. Stackademic — Clear, Structured Python Tutorials

Stackademic leans more toward structured, educational content.

The difference shows in how tutorials are written.

concepts are introduced step by step
explanations are given proper space
articles tend to build on ideas rather than jump straight to results

For Python developers, this makes it useful when:

you want a more guided learning experience
you prefer clarity over speed
you are trying to connect different concepts

Compared to DEV Community, it feels more curated and more consistent in tone.

5. Talk Python — Staying Connected to the Python Ecosystem

Talk Python is slightly different from the others because it combines a blog with a podcast.

That gives it a broader perspective.

Instead of focusing only on tutorials, it also covers:

industry trends
new tools and libraries
insights from people in the Python community

It’s a good way to stay updated on what’s happening beyond just code.

If you want to understand where Python is heading, not just how to use it, this is worth following.

6. PyImageSearch — Deep Dive into Computer Vision

If your interests lean toward computer vision, PyImageSearch is one of the most useful niche Python blogs.

The content is focused and technical.

image processing
deep learning
OpenCV-based tutorials

What stands out is the depth within that niche.

Instead of covering everything, it goes deep into a specific area, which makes it especially valuable if that’s relevant to your work.

7. Hashnode (Python Blogs) — A Network of Independent Voices

Hashnode is not a single Python blog, but a platform where developers run their own blogs.

That leads to a different experience.

a mix of beginner and advanced content
different perspectives and approaches
a wide range of topics

Over time, you can find individual writers whose content you trust and follow them directly.

It’s less curated than some of the other options, but it gives you access to a broader set of viewpoints.

How to Get the Most Value From These Python Blogs

Following multiple blogs only works if you use them intentionally.

A simple way to approach it:

use Real Python or Stackademic for deeper learning
use DEV Community for practical insights
use Talk Python for ecosystem awareness
use In Plain English for a steady flow across topics

This way, you’re not relying on a single source to do everything.

Frequently Asked Questions (FAQ)

What are the best programming blogs for Python developers?

Some of the best include In Plain English, Real Python, DEV Community, Stackademic, Talk Python, PyImageSearch, and Hashnode.

Which Python blog is best for beginners?

Real Python and Stackademic are strong options because they focus on structured, easy-to-follow tutorials.

Are community platforms like DEV Community useful for Python learning?

Yes. They provide real-world examples, discussions, and practical insights that complement more structured learning resources.

Should I follow multiple Python blogs?

Yes. Different blogs serve different purposes, and combining them gives you a more complete view of the ecosystem.

Is it better to follow niche Python blogs or general developer platforms?

Both are useful. Niche blogs provide depth, while broader platforms provide variety and context.

Final Thoughts

After spending time with these, the biggest difference wasn’t just in content quality, but in how each one fits into your routine.

Some are the kind you open when you’re trying to learn something properly. Others are easier to check in on regularly and pick up ideas as you go.

That makes a difference in what you actually end up using.

Instead of trying to find the single best Python blog, it’s more useful to figure out which combination you’ll realistically keep coming back to.

I Fixed a Documentation Problem in 24 Hours That Had Slowed a Team for Weeks

Sun, 26 Apr 2026 21:13:02 +0000

A team reached out with a problem that sounded familiar:

“Our product works. But users keep getting stuck.”

They had already tried to fix it.

They added more explanations.
They expanded their documentation.
They even walked users through things on calls.

But nothing really changed.

The Real Issue

When I looked at their documentation, one thing stood out immediately:

It wasn’t bad.

It was just hard to follow.

What Was Going Wrong

Everything was technically correct.

But:

• The starting point wasn’t clear
• Important steps were buried in long explanations
• Examples assumed too much context
• Users had to “figure things out” instead of being guided

So instead of moving forward…

Users paused.

And when users pause too long, they don’t keep going.

They leave.

What I Did (In 24 Hours)

I didn’t rewrite everything.

I focused on one goal:

Make it obvious what to do first

Here’s what I changed:

• Created a clear “start here” entry point
• Broke down key actions into simple, direct steps
• Removed unnecessary technical noise
• Rewrote examples to be beginner-friendly
• Highlighted expected outcomes at each step

I treated the documentation like a path, not a reference.

The Immediate Impact

Within a short time, the difference was noticeable:

• Fewer basic questions from users
• Less need for onboarding calls
• Faster time to first success
• More confident users interacting with the product

Nothing about the product changed.

Only the clarity did.

Why This Worked

Most teams think documentation problems require:

More content
More detail
More explanation

But in most cases, the issue is:

Too much thinking required from the user

Good documentation reduces thinking.

It removes guesswork.

It guides action.

What This Means for You

If your team is:

• Explaining the same things repeatedly
• Watching users struggle to get started
• Relying on calls to guide onboarding
• Adding more docs but seeing no improvement

Then the problem isn’t effort.

It’s structure.

A Simple Test

Open your documentation and ask:

“Can someone succeed here without asking for help?”

If the answer isn’t a clear yes…

There’s work to do.

Final Thought

You don’t need weeks to fix confusion.

Sometimes, you just need to see it differently.

If your product works but users still struggle to understand how to use it…

That’s exactly what I help fix.

I turn slow, confusing onboarding into clear, usable experiences—fast.

Technical Writing for Beginners: A Simple Guide with Examples

Tue, 21 Apr 2026 21:07:57 +0000

Have you ever tried to follow instructions in a software program, only to end up more confused than when you started?

This often happens when instructions are not written clearly or when too many technical terms are used without explanation. Good technical writing helps solve this problem by making complex information easier to understand.

In this guide, you will learn what technical writing is, see practical examples, and discover a few simple tips to help you get started as a beginner technical writer.

What is Technical Writing?

Technical writing is the process of writing complex information into easy-to-understand content. However, the goal is not to sound complicated, but make things simple for the readers to understand.

Example

Instead of saying:

The application facilitates communication between users.

A technical writer will write:

The app allows users to send messages to each other.

In this example, the second sentence replaces the complex and formal terms (facilitates, communication) in sentence one, with direct verbs (allows, send). This makes the information easier for readers to understand.

The main goal of a technical writer is to turn complicated ideas into clear instructions that users can quickly follow.

Other Examples

Topic 1: How to Install a Mobile App

Complex Example

After downloading the application, execute the installation procedure and configure the settings appropriately.

This sounds too complex and unclear.

Simple Technical Writing Example

How to Install the App

Open the Google Play Store
Search for the app name
Tap Install
Wait for the download to finish
Open the app and follow the setup instructions

This version works for three reasons:

It uses numbered steps so readers can track their progress
It uses plain, active verbs (tap, search, open) instead of vague ones (execute, configure)
It speaks directly to the reader using "you"

These three habits: numbered steps, active verbs, second person voice are cornerstones of good technical writing.

Topic 2: Connecting to Wi-Fi

Complex Example

Establish a wireless network connection by opening the device network configuration interface, selecting the desired SSID and providing the correct security credentials.

Simple Technical Writing Example

Open Settings → Wi-Fi, select your network, enter the password and tap Connect.

The other example is preferable because it changed the technical jargon (establish, configuration, desired SSID) used to relatable verbs (open, select, enter). This process compressed the first example into simple instructions, which is the purpose of technical writing.

Where Technical Writing Is Used

Technical writing is used in many areas of technology, such as:

Software Documentation
These are guides that explain how software works and how to use it.
Example: A guide explaining how to use Microsoft Word or Zoom features.
Product Manuals
Step-by-step instructions for setting up or using a product.
Example: A phone or blender manual.
Tutorials and Guides
Instructions that teach users how to complete a task.
Example: How to create a Gmail account.
Instructions for Developers
Instructions on how to use software tools, apps, or services.
Example: Using an API.
Help Center Articles
Short articles that answer common questions or solve problems.
Technical Blog Posts
Articles that explain technical topics in a simple way.

Tools Used for Technical Writing

When starting technical writing, some tools can make the process easier.

Markdown
A simple formatting language used for writing structured documents.
Google Docs
Useful for drafting articles, editing content and collaborating.
Grammarly
Helps check grammar, spelling and clarity.
Notion
Helpful for organizing notes and writing ideas.
Hashnode
A platform for writing and publishing technical blogs.
Confluence
Used by companies for internal documentation.

If you're just starting out, begin with Google Docs and Grammarly. You can learn the others as you grow.

Tips for Beginners

1. Audience Awareness

Before you write a single sentence, ask yourself:

Who will read this?
What do they already know?
What do they need to be able to do after reading this?
What is the simplest way to explain this?

Knowing your audience is what separates useful technical writing from writing that just sounds technical.

2. Start with Easy Topics

Begin by picking simple tasks like:

How to reset a password
How to send an email

3. Avoid Hard Words

Use simple words everyone can understand.

Instead of:

Authenticate your credentials

Write:

Enter your username and password

4. Use Headings and Lists

Break your content into headings and lists.

Example: How to Take a Screenshot

Press the Power and Volume Down buttons together
Wait for the screen to flash
Open your gallery to view the screenshot

5. Give Examples

Show how things work with short examples. Use step-by-step instructions or screenshots to improve understanding.

6. Practice Writing

Write short, simple guides regularly.

Create a mini-guide like:

How to share a file online

Try publishing it on a blog.

Conclusion

Practicing technical writing helps you communicate clearly, think logically, and solve problems step by step. It also builds a portfolio that shows your skills to potential employers or collaborators.

Start small. Pick any app or tool you use daily and write a step-by-step guide explaining how to use it.

Share it on dev.to and tag it #technicalwriting. The feedback you receive will accelerate your growth faster than writing in private.

The more you practice explaining technical topics clearly and simply, the better you will become.

Before You Hire a Technical Writer, Watch How Your Team Explains Things

Sat, 18 Apr 2026 23:34:02 +0000

A lot of teams think they need a technical writer because:

“Our docs aren’t great.”
“We need better explanations.”
“We should probably clean things up.”

That’s not the real signal.

The real signal is this:

How your team explains things when someone asks for help.

What I Look For Immediately

Whenever I work with a team, I don’t start with the documentation.

I start with conversations.

Slack threads.
Onboarding calls.
Internal explanations.

Because that’s where the truth shows up.

The Pattern That Always Appears

Someone asks a simple question.

“How do I do X?”

And the answer looks like this:

“Okay, so first you need to understand how our system handles Y…”
“Then there’s this edge case you need to be aware of…”
“Oh, and depending on Z, it behaves differently…”

Five minutes later…

The person asking the question is already overwhelmed.

That’s the Problem

Your documentation isn’t failing because it’s missing information.

It’s failing because your thinking isn’t structured for the user.

The confusion in your docs usually already exists in how your team explains things.

Documentation just exposes it.

What I Actually Fix

When I step in, I’m not just rewriting sentences.

I’m restructuring how information flows.

That means:

• Turning long explanations into clear steps
• Separating “must know” from “nice to know”
• Aligning everything around real use cases
• Removing unnecessary cognitive load

Because clarity isn’t about writing more.

It’s about making decisions on what matters first.

A Simple Test You Can Run Today

Next time someone asks your team a question:

Watch how long it takes to explain.

If it takes more than a few minutes to make it clear…

Your documentation isn’t the only thing that needs work.

The Shift Most Teams Don’t Make

They try to improve documentation after everything is built.

But the real improvement comes from fixing:

how things are explained in the first place.

Final Thought

Good documentation doesn’t start with writing.

It starts with clear thinking.

If your team keeps explaining the same things in different ways, and it still feels confusing…

That’s exactly the kind of problem I help solve.

I don’t just rewrite docs.

I make your product easier to understand.

If Your Documentation Needs a Meeting to Explain It, It’s Already Broken

Thu, 16 Apr 2026 06:52:39 +0000

There’s a quiet pattern in a lot of teams.

Someone shares documentation.

And then immediately says:

“Let me walk you through it.”

That’s the Problem

If your documentation needs a meeting to make sense…

It’s not documentation.

It’s a script.

Where This Usually Starts

The docs exist.

They look complete.
They cover the system.
They explain the features.

But when someone new tries to use them…

They get stuck.

So a call gets scheduled.

And during that call, everything suddenly becomes clear.

What the Meeting Is Actually Doing

The meeting isn’t just explaining the docs.

It’s adding what the docs are missing:

• Context
• Intent
• Real examples
• Clear direction

The human fills in the gaps the documentation left behind.

The Hidden Cost

At first, it feels normal.

“Let’s just jump on a quick call.”

But over time, it becomes expensive:

• Same explanations repeated over and over
• Slower onboarding
• Knowledge locked in people, not systems
• Teams becoming dependent on specific individuals

Now your documentation isn’t scaling.

Your people are.

What Good Documentation Replaces

Great documentation removes the need for meetings.

Not completely.

But for the basics? Absolutely.

It should allow someone to:

• Get started without asking for help
• Understand what to do next
• Solve common issues on their own

Without waiting for someone to be available.

A Simple Test

Before sharing documentation, ask:

“Can someone use this without me being there?”

If the answer is no…

The work isn’t done yet.

The Shift That Changes Everything

Stop writing documentation as if you’ll always be there to explain it.

Start writing it as if:

The reader is on their own.

Because most of the time…

They are.

Final Thought

Documentation shouldn’t depend on people.

People should depend on documentation.

If your team keeps explaining the same things in calls, Slack threads, or onboarding sessions…

That’s not a communication habit.

It’s a documentation gap.

And that’s exactly what I help teams fix.

The Day You Realize Documentation Isn’t for You

Fri, 10 Apr 2026 15:57:01 +0000

There’s a moment most developers don’t notice when it happens.

You’re writing something.

Maybe a README.
Maybe a quick guide.
Maybe just a comment to “explain things later.”

And without thinking, you write it like this:

“Just run this…”
“Obviously, you need to…”
“Make sure you already have this set up…”

It feels normal.

Because in your head, it is obvious.

Until Someone Else Reads It

A new developer joins.

Or a teammate picks up your work.

Or worse, you come back to it weeks later.

And suddenly…

Nothing is obvious anymore.

That “simple step” is confusing.
That “quick setup” is missing pieces.
That “just do this” assumes too much.

And now, instead of helping…

Your documentation slows things down.

The Shift Most People Miss

Documentation stops being about you the moment you write it.

But most of us don’t adjust.

We write from memory.
From familiarity.
From inside the system.

Not from the perspective of someone seeing it for the first time.

What Makes Documentation Actually Work

It’s not more detail.

It’s better awareness.

Good documentation quietly answers questions like:

“What am I supposed to do first?”
“What might go wrong here?”
“What am I missing that everyone else seems to know?”

Because that’s where people get stuck.

Not in complexity.

In assumptions.

The Problem With “Just Enough” Docs

A lot of teams aim for “just enough documentation.”

But “just enough” for the writer is often not enough for the reader.

So users:

• Fill in gaps incorrectly
• Make assumptions that break things later
• Lose confidence before they even start

And once that confidence is gone…

It’s hard to get it back.

A Small Habit That Changes Everything

Before you write anything, pause and ask:

“What would confuse someone seeing this for the first time?”

Then write for that version of the reader.

Not for yourself.

The Real Job of Documentation

It’s not to prove you understand the system.

It’s to make sure someone else doesn’t feel lost using it.

Final Thought

Good documentation doesn’t sound smart.

It makes the reader feel smart.

If you’re building something and people keep getting stuck, asking questions, or misusing your product…

It’s rarely because they’re not capable.

It’s because something wasn’t made clear.

That’s the gap I focus on fixing.

Your API Isn’t Hard to Use. It’s Hard to Understand.

Fri, 10 Apr 2026 00:37:36 +0000

Most teams assume users abandon their API because it’s too complex.

Too many endpoints.
Too many parameters.
Too many edge cases.

But that’s rarely the real reason.

Developers don’t abandon APIs because they’re complex.

They abandon them because they feel lost.

The Moment You Lose Your User

It doesn’t happen after hours of struggle.

It happens in minutes.

A developer lands on your documentation, trying to do something simple:

“Create a user.”
“Send a request.”
“Authenticate.”

They start reading.

And immediately, things feel off.

The explanation assumes too much.
The examples skip steps.
The terminology isn’t consistent.
The “getting started” guide isn’t actually getting them started.

So they try to figure it out themselves.

They guess.
They experiment.
They retry.

And then…

They leave.

Not because your API is bad.

But because your documentation made them feel like they were the problem.

Confusion Feels Like Failure

Here’s what most teams underestimate:

When a developer doesn’t understand your documentation,
they don’t blame your docs.

They blame themselves.

“I should get this.”
“Maybe I’m missing something.”
“Let me try again.”

That feeling doesn’t last long.

It turns into frustration.

And frustration turns into abandonment.

What Good API Documentation Actually Does

Good documentation doesn’t just explain your API.

It guides thinking.

It answers questions before they’re asked:

What is this API for?
When should I use it?
What’s the simplest thing I can do right now?
What happens if something goes wrong?

It removes doubt.

Because clarity is not about adding more information.

It’s about removing friction.

The Problem With Most API Docs

Most documentation is written from the inside out.

It reflects how the system was built, not how it’s used.

So instead of:

“Here’s how to create a user in 3 steps…”

You get:

“Users are managed via the /v2/core/user endpoint with optional flags…”

Technically correct.

Practically useless.

The Shift That Changes Everything

Instead of asking:

“How do we document this system?”

Ask:

“What does the user need to feel confident using this?”

That changes everything.

Because now you:

Start with real use cases
Show working examples early
Explain decisions, not just structure
Remove unnecessary complexity

You stop documenting features.

You start enabling outcomes.

A Simple Standard Most Teams Don’t Follow

Every API should make one thing effortless:

The first successful request

Not a perfect integration.
Not full understanding.

Just one working result.

Because that first success builds momentum.

And momentum keeps users.

What This Means for Teams

If your API adoption is low…
If support keeps answering the same questions…
If onboarding takes longer than it should…

It’s not just a technical issue.

It’s a documentation issue.

And fixing it doesn’t require rewriting your system.

It requires rewriting how you communicate it.

Final Thought

Developers don’t need perfect APIs.

They need clear paths.

Because in the end, people don’t stick with tools they don’t understand.

They stick with tools that make them feel capable.

If you’re building APIs or developer-facing products and your documentation isn’t doing that…

That’s exactly what I help fix.

I turn complex systems into clear, usable experiences developers actually enjoy working with.

Book review: Writing for Developers

Thu, 29 May 2025 07:18:24 +0000

Disclaimer: This post includes affiliate links; I may receive compensation if you purchase the book from the different links provided in this post.

This review is about Writing for Developers by Piotr Sarna and Cynthia Dunlop from Manning.

I started my blog as a hobby seventeen years ago, in April 2008. At the time, I had no clue about technical writing. I'm pretty sure it was not even a thing back then: the only content aimed at developers was technical documentation. Since then, the landscape has changed a lot, to the point that companies hire for technical writer positions.

I was curious to compare what I learned by doing to the structured approach of a book. I ordered the book last year when it was still being written. It was published only early this year, and I was already reading (and reviewing!) DuckDB in action. I put it on the top of my reading pile list; I finally finished it: here's my review.

Facts

17 chapters, divided into four parts
2 appendices
345 pages
$39.99 (eBook)

Chapters

Part 1 - Fundamentals

Why write
What to write
Captivating readers

Part 2 - Nailing the writing process

Creating your working draft
Optimizing your draft
Getting feedback
Ship it

Part 3 - Applying the blog post pattern

The "Bug Hunt" pattern
The "Rewrote It in X" pattern
The "How We Built It" pattern
The "Lessons Learned" pattern
The "Thoughts on Trends" pattern
The "Non-markety Product Perspectives" pattern
The "Benchmarks and Test Results" pattern

Part 4 - Promotion, adaptation, and expansion

Getting attention
From blog post to conference talk
So you want to write a book

Pros and cons

In the first chapter, the authors list the most common reasons developers mention not to write posts. I have heard many of these reasons and can confirm their existence. Then, the authors address each of them and provide multiple counter-arguments.
Part three is dedicated to blog post patterns; each chapter describes a pattern in detail. Reading this made me realize that most blog posts fall into a specific and easily identifiable category. The authors structured each pattern-chapter into the following sections:
- Purpose: what's the idea (or ideas) behind the pattern
- Audience: who does the pattern target
- Examples: a couple of existing blog posts that embody the pattern
- Characteristics: common traits found among the posts of this type
- Dos and don'ts
I do love typologies, and I found this breakdown very useful.
I found part four less relevant, especially since cross-posting has been part of my workflow for ages, and I reuse writing content for conference talks. If you never considered these options, you'll benefit from these chapters.
The only con I found is that the authors remind us that you should ask your company before you reveal trade secrets. I understand that you would like to warn people, but when it's repeated several times throughout the book, I got the feeling they're writing to dummies–not something I'm fond of.

Summary

If you're a technical writer, a Developer Advocate tasked with technical writing, or a regular developer who wants to start a blog or contribute to a company blog, I recommend getting this book. The exhaustive description of common patterns is a huge asset for beginning writers and can help even seasoned ones.

Originally published at A Java Geek on May 25^th, 2025