You hear all the time about teams struggling to create and maintain E2E tests that keep pace with the speed at which they’re shipping. They might initially invest time in creating an initial suite only to watch the suite turn flaky, slow, or get ignored when failures pile up [1].

I’ve heard people talk about using Claude Code for QA and wanted to see if Claude could help with the planning side of QA work: test planning, generating specs, running tests locally, setting up GitHub Actions, and updating tests when the UI changed.

As part of my test, I built a production-ready Airbnb-style hotel app called Bunkly, complete with search, checkout, loyalty, and messaging. I decided to start with a clean slate, an app with no Playwright tests yet.

I have attached the full Claude Code transcript [2] for you to read alongside the blog.

The Bunkly codebase was designed to be deliberately test-friendly. Interactive elements carry `data-testid` attributes, seed data is deterministic (fixed slugs and known passwords in `CLAUDE.md`), and `ARCHITECTURE.md` explains how Server Components and server actions split responsibilities.

You’d think that would make things straightforward. Instead, I hit selectors that weren’t in the code, odd feature priorities (wishlists ranked above booking), and CI jobs that skipped hidden directories.

This post covers what happened at each step of trying Claude Code for QA testing, what worked, what broke, and what I still had to verify in the code, seed data, and CI logs.

Set up Bunkly locally

The first step was to get Bunkly running locally. I cloned the repository and seeded the database with the following commands:

git clone https://github.com/rishi-raj-jain/bunkly
cd bunkly
npm install

cp .env.example .env   # set DATABASE_URL

npm run db:migrate     # or db:push in dev
npm run db:seed

npm run dev            # http://localhost:3000

The seed step creates about ten to fifteen properties across five cities, rolls inventory forward for a year, and adds users with plaintext passwords for test automation. Without that seed data, flows like logging in as a user named Sarah, viewing upcoming bookings, or testing loyalty enrollment would have nothing to assert against.

To enable browser-aware changes in Claude Code, I also set up the Playwright MCP so threads could refer to real navigation and DOM behavior along with file changes.

Claude for QA Test Planning

Before automating the tests via code, I asked Claude for a test plan keyed to Bunkly’s main workflows, e.g., discover properties, complete a booking end-to-end, manage profile and payment methods, notifications, message threads, loyalty (where seed allows), and secondary flows like wishlists and price alerts. Here is the prompt I used:

Produce a prioritized E2E test matrix in docs/cc-test-plan.md with P0/P1/P2 cases.

Claude’s first attempt at a test plan was thorough on the surface. It covered the major features and some lesser-used ones, such as price alerts, wishlists, reviews after check-out, and flows for editing bookings. The plan was laid out as a large table with P0, P1, and P2 priorities and tried to balance common paths with edge cases.

Taking stock of the app’s features was genuinely helpful. It forced me to consider corners of the product I might have skipped otherwise.

Here are a few prompts I sent after the initial test plan was generated (source):

can you move the tests from P2 to PQ that makes sense, we are a booking company so we need the ability to make sure that search is the top priority

but how is wishlist a P1?

why adding payment method is P1?

why did you move payment method to P2? It was in P1 and it should be a P0 instead since we need to be able to process money!

why in the world is forgot password a P2?

Several important gaps around using Claude for QA became clear when I reviewed the test plan:

• The priorities in the plan (e.g., high/medium) didn’t always match practical risk-cosmetic toggles, which were marked higher than critical for end-to-end booking flows.
• Some scenarios described in the plan didn’t align with what’s possible in the current codebase. For example:
  - The plan included saving wishlists, but the UI and seed data didn’t allow wishlist actions for any seeded user, so these tests were not feasible.
  - Review tests referenced features without establishing the necessary preconditions. Review flows require users with prior completed bookings. Without seeded bookings for the user, these tests could never run as intended.
  - Messaging tests assumed the existence of seeded conversations linked to a user. Without a specific database setup for these conversations, messaging tests could not execute successfully.

There was a disconnect between feature coverage on paper and what could be executed, as the plan didn’t specify the test prerequisites or acknowledge app limitations. Overall, these mismatches highlighted the need to bridge the gap between the features listed in the plan and the test scenarios that can actually be run manually.

For this kind of app, making every test scenario actually useful means spelling out things like the specific user account (with credentials pulled from CLAUDE.md), how to navigate to the right page, which selectors to use (and making sure they match real data-testids from the codebase), what should change in the database if the test performs a mutation, and how to reset everything between runs to keep things clean and reproducible.

Claude was great at firing off a wide-ranging list so I didn’t forget anything major, but it couldn’t translate that list into something directly actionable, something I could truly trust day-to-day, or something I could hand to someone to use for proper QA.

Claude for E2E Test Generation

Once the test plan was refined (and I had it create the final one in `cc-test-plan-after.md`), I asked Claude to generate Playwright tests accordingly, with the following prompt:

now read the cc-test-plan-after.md file and then write the tests using playwright (feel free to use the playwright mcp if required)

Once the initial tests were scaffolded, I followed up with operational instructions (wonder why Claude hadn’t done that):

add the instructions to run the tests in README.md

And to ensure the automated runner would actually hit the production build, I needed to specify (since Claude didn’t pick that up automatically):

to run the web server, use npm run start and not npm run dev

The output included a standard Playwright structure: a playwright.config.ts file (with the webServer command), global setup scripts, a set of initial spec files in the tests/e2e/ directory, and some helpers for navigation and repeated interactions. While I hadn’t used Playwright’s multiple project configuration model before, the generated split between a general setup project and an authenticated-user project matched what I would have done.

Next, I ran npx playwright test and encountered a set of initial failures, including:

• Incorrect selectors and URLs in the tests
• Assertions that did not match the actual DOM structure
• Incorrect step order and issues related to async UI updates
• Test navigation/routes and business logic that were not aligned with the codebase
• Use of test.skip() in place of a proper seed-backed test setup
• Tests missing authentication contexts

To better understand the causes of these failures, I examined each issue in detail. Below, I break down what went wrong in each area.

Issue 1: Tests didn’t use the right selectors and URLs

Although CLAUDE.md carefully documents the expected data-testid attributes for interactive UI elements, the generated Playwright specs referenced the test IDs and selector names that simply do not exist in the codebase.

• For example, the specifications for profile updates assumed the presence of a profile-form wrapper, however, upon inspecting the relevant React components, it became clear that no such element is defined with that identifier. To fix this, I referenced the source code directly.

Another source of test failure was the mismatch in the query parameters used:

• For example, the application expected a destination query parameter on the results page. However, both the generated specs and a reusable helper function used the parameter name location instead. This single issue affected multiple specs because it was present in shared navigation code, resulting in every search-related test failing.

These adjustments definitely made me aware that anyone using Claude Code for QA testing needed to be someone who understood how the application source and test code behaved, so they could correct them rather than rely on Claude’s assumptions, especially as both code and tests change over time.

Issue 2: Tests didn’t make assertions based on the actual UI

For example, the payment method specs asserted that the first four digits of a card should be displayed after adding it. However, the wallet UI is designed to display only the last 4 digits to comply with PCI best practices. As a result, the test assertion failed every time.

I noticed similar issues when tests made assertions about UI text or record counts that didn’t match the seeded data (for example, expecting a certain number of notifications even though no notification rows were populated during setup).

These mismatches suggested the tests were partly based on assumptions about the intended UI rather than on the actual state and structure of the codebase Claude was working on. The need to check output for this adds extra time and risk if using Claude Code for E2E testing.

Issue 3: Tests didn’t handle async UI timing or state

One flow expected a service-section to be visible before the user opened the service request entry point. The app renders that section after the click.

Another spec toggled a notification category and immediately called page.reload(), overlapping React useTransition on that settings page. The runner reported timeouts and stale state that looked like flakes until I reordered steps and waited on the right locators.

I told Claude to always use expect(locator).toBeVisible() (not assumptions), reference real data-testids from components, check server actions for business rules, and use networkidle only when truly needed. After tightening waits and removing a reload, failures dropped from 8 to 3, showing which were timing vs. logic issues.

However, investigating and fixing these issues took time and reduced the time savings I was hoping to realize from using Claude Code for QA.

Issue 4: Tests didn’t check real routes or logic

For example, some test specs made assumptions about app routes or business logic without checking the implementation:

• Price alert tests tried to visit /alerts, assuming a standalone alerts page existed, but in reality, price alert functionality lives within each property (properties/[slug]/) and in the account’s price alert settings (not a top-level route).

• One of the messages spec navigated to /messages/ (with a trailing slash) and tried to confirm the presence of that URL even though the app is navigated at /messages (no trailing slash).

• Review-related specs attempted to review upcoming bookings, when in fact (as enforced by both reviews.ts and seeded data) only completed stays are eligible for reviews.

Issue 5: Tests didn’t set up required state

When flows needed two payment methods on file, or a non-default card to delete or to switch default, the agent sometimes emitted test.skip() with a comment that setup was hard. Skipped tests do not exercise the feature and still count toward green in CI.

I asked for explicit navigation to payment settings, seed-backed users, or a beforeEach that creates the second method through the same UI path a user would take.

Issue 6: Tests didn’t handle authentication properly

Initially, several tests attempted to access protected routes without logging in, resulting in redirect and timeout errors. Playwright’s dependencies config (like dependencies: [‘setup’]) wasn’t used by default, so not all tests reused the established session until I pointed it out.

Claude for QA: Parallel test runs and the impact of shared database state locally

After debugging specs in isolation, I enabled fuller parallel execution (fullyParallel and multiple workers). Loyalty point assertions and review submission collided when workers logged in as the same seeded user and mutated the same rows.

I pasted worker logs and stack traces into Claude. It suggested grouping the unstable suites with test.describe.configure({ mode: ‘serial’ }) so those no longer run concurrently. I had not used that API on this project before and it was the right tool for the symptoms.

Cases that failed only under parallel load included loyalty balance checks after redemption-style flows and review submission that changes booking or review rows. Serial mode stabilized them locally and I kept a mental list of which domains are read-only versus write-heavy for future sharding when I deploy the tests to CI.

Claude for QA: Managing environment variables, jobs, artifacts, and dotfiles in GitHub Actions

The next step after confirming that everything worked fine locally was for me to move the suite to GitHub Actions (CI).

My Claude Code QA agent’s produced workflow was recognizable i.e. checkout, install dependencies, run seed, shard tests, upload reports. I added DATABASE_URL to the repository secret so that it was accessible. It didn’t go smoothly:

• The first failure was environmental i.e. the seed script read DATABASE_URL from .env locally and required me to prompt the agent to wire it down via the repository secrets in the workflow code.

• Authenticated specs depended on files under tests/.auth/ produced during a setup job. The setup job logged in and wrote storageState to disk. Consumer jobs restored node_modules from cache but not the auth directory. Auth specs then failed or passed depending on whether they accidentally performed login again in the spec body.

• I still had a gap after auth-related tests improved. The setup job had run in the logs, but tests/.auth/ did not appear in the uploaded artifact bundle. The agent’s first explanation was that seed had not run but I knew that seed had run. So, I pointed at an artifact upload configuration and dot directories. GitHub’s default upload patterns often omit paths like .auth unless you include them explicitly in actions/upload-artifact.

• After adding the dotfile paths (or an explicit path to tests/.auth/**), later jobs downloaded the auth bundle and the workflow passed end to end.

Claude for QA: Updating tests when the product changes

After a stable CI run, I asked Claude to update with two UX changes in the application:

• To merge the stay and guest details into one step in the checkouts, and leave payment as the clearer second step.
• Drop the tabbed “upcoming / past” navigation in the bookings view for a single list with filters.

And as a result:

• Checkout edits by Claude mostly matched the new step order. The agent rewrote navigation through the combined step and adjusted payment-step assertions. It also tightened waits on a spec that had been green under loose timing (a race that showed up when step boundaries changed!).
• Bookings tests became harder to pass after the Claude edits as one spec silently passed. I knew it shouldn’t have happened since I removed the tab clicks, but I found that the tests were written so they searched for a specific property name that appeared regardless of the filter state. The assertion did not prove that the “past” filter changed the list (a false negative, CI green without guarding the behavior we changed).

I asked Claude to see what’s going on:

can you read the code and then tell me if clicking past-tab changes the booking-card- list? or does it just takes me to the same page but to the past bookings below the upcoming views instead of it being tabbed

and it finally came to senses with the following proposal:

The fix is to scope the locator to the past section:

const cards = page.locator('[data-testid="bookings-section-past"]
[data-testid”="booking-card-"]"');

That way the loop only iterates over cards inside #bookings-section-past,
regardless of scroll position. Want me to apply that fix?

After that, I simply asked it to read through the failed test results that were automatically reported in a standalone directory by Playwright:

can you read the test-results folder and then fix the tests?

From the logs, I saw that it fixed the add-on scenarios (like breakfast on pending versus confirmed bookings) with the new list-and-filter UI model and also clarified which seed user owned which booking states. For handling booking checks, it added serial grouping to ensure parallel workers were not writing to the same booking (or add-on records).

Advice for developers thinking about using Claude for QA testing

Overall, after having Claude update the code and write tests for the new feature, I saw that simple selector renames get handled quickly if I point the agent directly at the changes, but bigger workflow changes need new assertions that will actually fail if the old UX is still present. For example, things like asserting on filter state in the DOM, row counts, or booking ids that only appear under the right filter, rather than just checking if some property name appears anywhere on the page need new assertions.

After a redesign, I had to clearly define for the agent what “correct” means, rather than assuming it could infer it from the component diffs alone.

While Claude can be helpful for setting up E2E testing, it works best as a contributor to your process rather than an all knowing test author.

You can leverage its knowledge of Playwright APIs and common testing patterns, and it can help with initial scaffolding and fill out happy-path test flows, however, that’s all it does. If you have more complicated use flows, it will likely be very time consuming for you to use Claude for QA testing and it could miss testing critical things.

There’s also considerable manual work required in using Claude for QA. You need to guide it on your specific app’s routes, seed data nuances, environment setup, and workflow boundaries to be fully effective. While it can sort out issues like parallelization and CI artifact handling, you still need to review its output for context-specific correctness, as it may produce false positives or fragile test logic if left unchecked.

Blindly trusting Claude E2E test results or assuming your Claude Code QA agent fully understands new workflows might cause issues to slip through, especially when product changes affect how things work under the hood. Ultimately, Claude might be able to help you get started creating an end-to-end coverage plan but it’s not purpose-built for generating QA tests and so often misses things or creates flaky tests.

[1]: https://medium.com/codetodeploy/our-e2e-tests-were-flaky-we-deleted-half-of-them-8393bb419322

[2]: https://github.com/rishi-raj-jain/bunkly/blob/main/2026-05-26-185638-this-session-is-being-continued-from-a-previous-c.txt

(Co-authored with Rishi Raj Jain)

Trying Claude for E2E Testing on an Airbnb Clone was originally published in JavaScript in Plain English on Medium, where people are continuing the conversation by highlighting and responding to this story.

Headless Content Management Systems ( Headless CMS) are pre-built backend that allows for the creation, storage, and management of digital content and assets. Unlike traditional CMSs, a headless CMS is decoupled by default, that is the content repository (otherwise called backend) is separated from the presentation layer (frontend) making it easier to deliver content across multiple presentation layers via APIs and SDKs.

Using a Headless CMS means that you can efficiently manage content from a centralized repository, move from idea to production faster, and adapt to changing technologies.

Many headless CMS providers exist. However, with some of these headless CMS providers, developers often encounter challenges such as integration complexity, limited customization, vendor lock-ins, restricted data control, rigidity, and feature gaps. These challenges have led developers, product owners, marketing specialists, and content creators in search of a flexible, extensible, and scalable headless CMS solution.

OneEntry Headless CMS is a ready-made, flexible, user-friendly, and scalable backend that allows you to manage all your websites and applications from a centralized dashboard. With OneEntry, you can deliver content at scale to multiple platforms like websites, mobile applications, electronic devices, IoTs, etc.

This article will review the potential of OneEntry and how it can help you unlock unlimited scaling for your applications.

What is OneEntry?

OneEntry is a flexible headless CMS for content development, creation, and management from a singular platform.

It helps content-heavy applications like e-commerce and less content-heavy applications like business websites to scale, manage, and serve content seamlessly. It also reduces the financial costs and time consumption of building backend solutions for your applications from the ground up.

OneEntry’s simplicity, flexibility, and extensibility are some of the reasons it is a game changer for headless CMS.

It uses a modular architecture — that is, its system is divided into small independent parts called modules making it easily maintainable, reusable, and scalable.

The following are some of the currently available modules:

• Content management: The content management module is the system core of OneEntry. You can create catalogs, text, and pages, and add forms, blocks, and other elements to pages with this module.
• Attributes: Add attribute sets for pages, goods, news, blocks, etc. The input and value variations can be configured by default.
• Forms: Set up forms and forms interactions such as save to the base, send via email, and send to script with this module. Configure validation and placeholders.
• Blocks: The Blocks module holds the page elements showing the content.
• Administrators: Assign administrative privileges with various access permissions.
• Catalog: The Catalog module allows you to import goods, create new goods, and merge and configure them.
• Menu: The Menu module lets you create and configure the menu.

The OneEntry system allows you to manage and structure content in multiple languages, allowing for language-specific adaptations. It also offers a seamless experience for all users, from developers to content creators and marketing specialists. The system was built to scale by default and seamlessly handle projects of any difficulty level.

Why OneEntry Trumps Other Headless CMS

The following are some of the benefits of using OneEntry and why it trumps other Headless Content Management Systems.

• Flexibility and Scalability: The OneEntry system is geared to be flexible and scalable by default, serving content across multiple channels efficiently. Its scalability makes it suitable for distributing content for content-heavy applications. The system can scale horizontally to handle rapidly growing businesses and varying traffic enabling practically unlimited scaling. It is also presentation-layer agnostic — meaning that you can use whatever tool you want to build the front end.
• Omnichannel content delivery: OneEntry allows you to deliver content across multiple channels from a central repository, supporting personalization options across channels. You can easily reuse content across different channels.
• User-friendliness: OneEntry is arguably the most user-friendly headless CMS when compared to others. It has an intuitive interface that allows users to understand how to navigate and use its features.
• Multi-language support: Effortlessly internationalize and increase accessibility for your product with OneEntry’s multi-language support. Serving content in various languages gives your product a global reach. Displaying content in your user’s native language helps convey messages accurately, gives you a competitive advantage in the market, and enhances the user experience for your product.
• Ease of integration: OneEntry’s API and SDK expose a standard interface for interacting with the modules. You can interact with every available OneEntry module from your frontend via the REST API. OneEntry can also integrate seamlessly with third-party tools and services such as card providers, payment infrastructure, delivery services, etc.
• Extensibility: OneEntry is extensible so it allows you to bring in your module or use third-party modules without conflict. Integrate your modules using technologies like Node.js, Python, Ruby, Java, or whatever technology you decide.
• Improved developer experience: The OneEntry system is specifically designed for developers, content managers, and marketing experts, making it faster and easier to build complex applications, create & manage content, and spin up marketing campaigns.
• Customization: OneEntry is a customizable system for any needs. You can customize it to meet your project needs.
• Data portability: Easily export your product data as YML or CSV files. Your product data belongs to you and you can move them whenever you want — no vendor lock-in.
• Content structuring: OneEntry’s content modeling capabilities allow you to define complex content structures and relationships.
• Cost-effectiveness: OneEntry reduces development costs by eliminating the need for building a custom backend from the ground up. Plus, OneEntry has affordable plans to get you started.

OneEntry’s Features and Architecture

The following are breakdown of OneEntry’s features and architecture that makes it stand out among other headless CMS.

• Modularization: OneEntry uses a modular architecture. Services are decoupled and operate as small independent units making the system maintainable and reliable. The architecture is extensible, allowing you to integrate third-party modules.
• Cloud storage: The OneEntry storage system rests on powerful and modern cloud servers making it highly performant, with daily backups to ensure the preservation of content.
• Security: Security is at the core of OneEntry. It goes through routine maintenance and updates to keep it optimized. OneEntry issues a let’s encrypt certificate (mTLS) to help keep your application secure.
• Media asset management: OneEntry effectively manages multimedia content. The system is designed to efficiently organize, store, and retrieve large media files.
• Automatic image optimization: You can diversify your content with OneEntry’s automatically optimized images.
• Powerful servers: OneEntry servers are powerful and capable of handling large traffic. The load-balancing algorithm helps to route load across servers, preventing excessive load on a single server. The servers are increased regularly to further allow for load-balancing.
• Fast SSDs: OneEntry’s SSDs are fast. This makes fetching content from the content repository fast. The SSDs make file upload & download, and content delivery fast.
• PostgreSQL, MySQL, and MongoDB databases: Under the hood, OneEntry uses both relational and non-relational databases to store and manage content.
• API driven: REST API access to all modules. The API is fast and well-documented to ensure easy integration.

OneEntry allows you to manage, store, retrieve, and digital content across multiple channels without the hurdles found in other headless CMS.

The system incorporates all necessary tools used by developers, content managers, and marketing specialists for the successful operation of any business project.

It is flexible, user-friendly, and extensible allowing you to deliver content at scale.

You can build projects of any scale on it without worrying about performance or scale — its servers are optimized to handle high-volume traffic seamlessly.

The built-in multi-language support gives your product a global reach and an enhanced user experience.

Create a free account on OneEntry and experience for yourself the possibility of a truly flexible and scalable headless CMS.

That was the end of this blog. Today, I hope you learned something new.

If you did, please like/share it so that others can see it as well.

Thank you for being a regular reader; you’re a big part of why I’ve been able to share my life/career experiences with you.

Follow me on Twitter to get more software engineering articles.

Want to read more interesting articles

✅ my most popular articles that you might be interested in

• Why Learn React
• Good Parts of React
• Practice JavaScript.
• How to Learn ReactJS
• Modern JavaScript
• How to Create a Project with Vite
• React State Management

Originally published at https://theankurtyagi.com on December 18, 2023.

Bonus: How to Create high-value content that converts

Founded by the team behind In Plain English, Circuit is a strategic growth company for developer-focused software startups. We help companies produce a higher ROI on their content marketing efforts.

If you want to build a better content strategy, scale content operations, increase product awareness and adoption, and grow a community, we help brands make this happen.

→ Content Marketing Checklist

→ How to Create Better Content for Developers

→ The Key Ingredient Behind High Newsletter Open Rates

OneEntry: The Next-Gen Headless CMS was originally published in Venture on Medium, where people are continuing the conversation by highlighting and responding to this story.

Welcome to the first blog post in our new series, “How Technical Writing Can Supercharge Your Startup.”

In this series, I’ll show you how technical writing can benefit startups, from gaining visibility to building trust with your audience. As a provider of writing services to startups, I’ve seen the positive impact well-crafted content can have.

Today, I’ll start with an overview of how technical writing can boost your startup’s growth. Stay tuned for more posts on why writing is a vital tool for startups!

Introduction

Technical writing plays an important role in the success of a startup. It involves creating clear, concise, and user-focused documentation that explains how a product or service works. “ Strong views, weakly held. “ Put yourself out there, but stay on the hunt for dissenting opinions from smart and respectful people.

Writing software is halfway between writing a novel and building a bridge.

Technical writing tolerates and even encourages stylistic idiosyncrasies that traditional publishing would not accommodate. Lean into them.

Technical content is either timely or timeless, with almost nothing in between.

Image credit- “State of Developer Relations”- you can access the full report here.

The person who writes down the plan in an organization/startup has tremendous power. If you want to find the up-and-comers at a tech company, look into who’s writing the plan. Though they may not be coming up with all the ideas, you’ll know they have the energy, motivation, and skills to organize and communicate ideas in a written form.

Surround yourself and your startup with “lateral thinkers” who can’t help but come up with variant perspectives on everything they see in your product or service. They won’t always be right, but they always challenge your thinking and writing.

Investing in technical writing can have a substantial impact on your startup’s success. It not only benefits your users but also contributes to the efficiency and effectiveness of your internal operations. Remember that the goal is to produce documentation that is clear, concise, and understandable to your intended audience. As a result, user satisfaction, loyalty, and business growth will increase.

Remember- Media formats are cyclical. Nietzsche wrote in aphorisms and Twitter is aphorisms-as-a-service. Hip-hop brought back poetry. Montaigne pioneered the essay format and blogs brought them back into vogue.

Startups should write more manifestos, blogs, clean docs, and integration guides.

What is Technical Writing?

Over the last 3 years, I’ve worked off and on documentation, integration guides, and technical blog posts for 20+ startups. I started contributing during my role as a developer advocate at SuperTokens — an alternative to Auth0, Firebase Auth back in 2021 and helped developers transition to the new open-source user authentication.

I found I enjoy writing technical blogs and documentation, It is satisfying to produce high-quality technical writing that benefits others.

Ankur💻🎧💪 on Twitter: "I'm on the front page of Hacker Noon right now if not on Hacker News 😄My story got featured. 🙏 pic.twitter.com/nYPZvO6CHH / Twitter"

I'm on the front page of Hacker Noon right now if not on Hacker News 😄My story got featured. 🙏 pic.twitter.com/nYPZvO6CHH

I’ve read a lot of technical writing and documentation resources over the years. I’ve written about why every engineer should write and I’ve collected together my notes both to help me remember key points later in my career, but also as a tool to help me think about writing now.

GPT has revealed how much writing is pure pablum. Bland, lifeless, uninsightful, unoffensive, and not worth the price of the ink it was printed with. so good writers will become more important for your startups who can build and write excellent technical blogs and ChatGPT plagiarism is a complete non-issue. If you can’t out-write a machine, what are you doing writing?

If you’re a developer interested in writing technical blogs, I’ve written a complete dedicated blog on what technical writing is and how to write good technical blogs.

My Writing Principles

When doing technical writing, I always try to keep the following principles in mind.

• The goal of writing is to make tasks as simple and efficient for users as possible.
• Developers prefer to be shown rather than told and prefer to learn by doing.
• Help your users achieve their first success as soon as possible.
• Keep it simple and write in simple language.

Why is Technical Writing Important for Startups?

I’ve been writing technical content for the last 3 years. Here’s what I learned:

• Clear technical blogs and documentation help end users understand your product quickly and efficiently, reducing frustration and increasing satisfaction.
• Thorough technical writing shows that you take your product and your users seriously. It boosts your brand’s trust and confidence.
• New end users can quickly become proficient with your product if they have access to well-organized, easy-to-follow guides, integration, and docs.
• Well-structured technical blogs and documentation improve your website’s SEO, helping potential customers find you more easily.
• As your startup grows, you’ll need to onboard more employees. Good technical writing and documentation are essential for training new hires efficiently.

Here are a few examples of excellent engineering blogs:

• The Cloudflare Blog
• DoorDash Engineering Blog
• The Netflix Tech Blog

• Detailed technical blogs and documentation demonstrate that you have a well-thought-out product and business strategy, which can be appealing to potential investors and partners.
• End-user feedback from technical blogs and documentation is often invaluable for improving your product and identifying areas of confusion.
• Well-written blogs and documentation can be easily translated into other local languages, enabling you to reach a broader, global audience.
• Having superior technical blogs and documentation can be a significant differentiator, giving you an edge over competitors.

Gergely Orosz on Twitter: "An underrated way to attract great engineers to your company(drumroll)Have a great engineering blog.This means ENGINEERS write the blog, not content writers. And they give the "real deal" about challenges, learnings, failures.So few companies do this. A few that do: / Twitter"

An underrated way to attract great engineers to your company(drumroll)Have a great engineering blog.This means ENGINEERS write the blog, not content writers. And they give the "real deal" about challenges, learnings, failures.So few companies do this. A few that do:

Good Technical Writing = Organic Developer Marketing

Developers have a reputation for being averse to marketing, but that’s not necessarily true.

In reality, developers are gaining purchasing power and respect within businesses of all sizes. Employers recognise the importance of investing in tools to help developers stay productive and happy because good developers are difficult to find and retain.

The variety of developer tools has increased dramatically, ranging from IDEs to higher-level abstractions and paid services like GPT, including low-code tools.

Technical writing is a successful developer marketing strategy rooted in authenticity and understanding the audience. Startups should spend time with developers, both online and in-person, to grasp their needs and preferences.

Technical content should be genuinely helpful and educational, and it is often more effective when created by a fellow developer. Options include in-house engineers, developer advocates, community writing programs, freelance writers, independent software engineers come writers like myself.

Developers are present on platforms like X formerly Twitter, Hacker News, Reddit, and LinkedIn and love to read well-written technical blog posts.

Why Technical Writing Strategy Stand Out?

While I’ll admit that big tech companies and startups are getting better at reaching developers. I spent 13 years as a hands-on software engineer and technical leader before starting my blog as a marketing developer, so here are my thoughts on why technical writing is a great asset for startups.

Business-to-developer marketing (“B2D marketing”) describes marketing initiatives designed to reach developers and technical writing is one of the best ways to do it while being genuine, authentic and interesting.

Many startups struggle with B2D technical marketing because developers are more difficult to reach than the average consumer. Gimmicks like swags, free food coupons, free t-shirts or exclusionary events centred around alcohol are not the way to go.

Be interesting- Writing is by far the fastest way to get feedback from developers in software engineering.

Build a cool project with your product, write about it and share it in public to get feedback and iterate.

We all developers appreciate honesty. In recent times, I personally liked the blog page of Supabase. They’ve written some very cool blogs and achieved very good growth from their written content.

As a startup, this means you should be honest about your product in the community.

Many big tech hire developer advocates — someone with a technical background who will champion their product at live events.

Big tech companies like Google/Amazon/Meta/Netflix have teams of these people to give talks at conferences, do training sessions, and write technical content about their company’s products but the developer advocate role is not a good fit for most of the startups- because they’ve to moved fast and unfortunately many developer advocates are lazy and below average people.

Startups need highly skilled engineers in tech who can write and build their engineering blog a platform where people want to come every single week if not every single day.

Startups must leverage technical writing and documentation as marketing tools.

Image credit- “State of Developer Relations”- you can access the full report here.

Role of Technical Writing in Effective Communication

We can write many different types of technical content for software developers.

• Documentation is important, but very few startups leverage documentation as a marketing channel.
• Tutorials and how-to guides can help end-users see how to use your product in the real world.
• Awareness-driving content is created with the goal of increasing the top of your funnel and may be published on external partner sites for increased reach. Hashnode, DevTo, HackerNoon, and DZone are all free places to publish developer content.
• Blog posts on your website allow you to engage readers and increase sign-ups.
• Sponsor independent writers or senior engineer who writes a technical blog on their website or newsletters.

How Technical Writing Ensures Clarity and Understanding

Always write good examples by starting with real code this builds trust with clients and investors while writing in public.

My tactics for writing in public:

Someone recently in my Twitter DM asked me — “Hi Ankur, I’m a big fan of your blog but I have got a question- how do you deal with writing in public? People on the internet are such assholes, sometimes.”

I’ve often heard the advice “Either turn off or Don’t read the comments”, but I’ve gained a huge amount of knowledge from reading internet comments on my posts and other people’s posts from strangers over the years, even if sometimes people are jerks.

Always talk about real facts and be honest

I mostly talk about facts — either facts about startups or developer advocates about my experiences as a writer. In general, I’d say that people’s comments about facts tend to stay pretty normal. The main kinds of negative comments I get about facts about my mistakes. I mostly try to head this off by trying to be self-aware about my knowledge level on a topic and saying “I’m not sure…” when I’m not sure about something.

Edit and refactor mistakes

I make many mistakes in my blog posts because I write about a lot of things that are on the edge of my knowledge. When people point out mistakes, I edit the blog post and fix it. Generally, I’ll stay near a computer for a few hours after I post a blog post on my Twitter or LinkedIn timeline so that I can fix mistakes quickly as they come up.

Bridging the Tech Knowledge Gap: The Core Challenge in Startup Developer Relations Program

The survey report mentions that Content Development was a top job activity for Developer Relations practitioners in 2023, with a distinction between Content Development related to Education (55%) and Technical Content Development, such as documentation (50%)​. This highlights the importance of technical writing and content creation in engaging with and educating developer communities.

Top 3 Questions Every Startup Must Ask Before Starting a Technical Blog

Starting a technical blog can be a significant step for a startup, as it requires a thoughtful approach to ensure it serves its intended purpose effectively.

• the purpose of writing
• the target audience
• the kind of content to be created

Ask these questions if you’re starting a new blog for your startup.

Identifying the blog’s aim is crucial, whether it’s raising brand awareness, supplementing documentation, building an audience, or establishing thought leadership. Secondly, understanding and narrowing down the audience helps in tailoring the content accordingly. Lastly, deciding on the content format, whether it’s tutorials, roundups, case studies, features, Q&As, comparisons, or opinion pieces, aids in maintaining a consistent and engaging blog.

That’s it for this blog. I’ll keep writing on this topic and share more insight about more specific features in the next blog.

Stay tuned Until then, here are some of my most popular blogs you might like to read.

• Software Developers, Why Haven’t You Started Technical Writing Yet?
• How to Build Scalable Microservices with Amplication
• How to Use HarperDB Custom Functions

Originally published at https://theankurtyagi.com on October 20, 2023.

Bonus: How to Create high-value content that converts

Founded by the team behind In Plain English, Circuit is a strategic growth company for developer-focused software startups. We help companies produce a higher ROI on their content marketing efforts.

If you want to build a better content strategy, scale content operations, increase product awareness and adoption, and grow a community, we help brands make this happen.

→ Content Marketing Checklist

→ How to Create Better Content for Developers

→ The Key Ingredient Behind High Newsletter Open Rates

How Technical Writing Can Supercharge Your Startup was originally published in The Startup on Medium, where people are continuing the conversation by highlighting and responding to this story.