DEV Community: Uriel Bitton

Share a Keyboard Walkthrough When You Build in Public

Uriel Bitton — Tue, 20 Oct 2026 14:07:52 +0000

When you build in public, share a keyboard walkthrough of one product task with its starting conditions, visible focus path and observed result. Explain exactly what you checked and what you did not. A short walkthrough can expose a concrete obstacle and invite useful review without claiming that the whole product has passed an accessibility audit.

This is a different kind of build update from a polished feature tour. The useful artifact is a record someone else can follow. The public reader needs to know how you moved through the task, where the result changed and whether the explanation comes from an actual check or a hypothetical example.

Pick a task with an observable finish

Consider a fictional appointment tool. The task is to filter available sessions to one tutor and choose an open time. The start is the availability page with a known set of invented sessions. The finish is the selected session’s details, before any real booking is submitted. This gives the walkthrough a clear boundary.

A tour of every interactive element on the site would be a different project. Start with the task your build update is about. If you are discussing a new filter, the reader should be able to see how the filter relates to the choice that follows. Do not make the public example depend on private customer information.

Write the expected result in ordinary language before checking. In this fictional case, the chosen tutor’s sessions should be available to inspect, and the person should be able to move onward from the filter. That expectation is specific enough to compare with a recorded observation. “Everything should be accessible” is too broad for this single note.

Learn the relevant keyboard checks

The DWP Accessibility Manual’s keyboard-testing guide describes checks for operating controls, logical focus order, visible focus and getting out of interactive areas. It also explains that keys can vary with the browser. Use the guide to understand the check before recording a public demonstration; a checklist alone is not a result.

For this walkthrough, focus means the element currently receiving keyboard input. You need to be able to identify that element as you move. If you cannot see where input will go, note the uncertainty rather than using the mouse to rescue the recording and presenting the sequence as keyboard-only.

Keep the browser and operating-system context in your private check note and in the public report when relevant. If a setting changes how the task behaves, record it. The point is to make the observation inspectable, not to imply that every visitor’s keyboard configuration will produce an identical sequence.

Keep the starting conditions reproducible

Use a test page or account you are authorized to use and create invented appointments. Record the product version or date, the page state and any setup needed to reach it. You do not need to publish an account identifier or access credential. Explain the state without exposing the private route used to prepare it.

Begin with a fresh pass through the task so you do not accidentally rely on focus or a filter value left over from a previous attempt. If the product remembers a selection, include that behavior in the conditions or deliberately reset it using the normal interface. A reader cannot reproduce a starting state that your report leaves unstated.

The fictional example could use three sample sessions with clearly different tutors and times. These are test fixtures, not customer bookings or evidence of demand. Say that the data is invented. A small, recognizable set makes it easier to tell whether the filter actually changes the available choices during the walkthrough.

Record actions and observations separately

Keep a short sequence with two kinds of information: the action you took and what you could observe afterward. For example, the hypothetical note might say that focus reached the tutor filter, a tutor was selected and the displayed session list changed. The next observation might concern where focus went when the person continued.

Do not infer the underlying implementation from that sequence alone. A visible pause does not establish a network problem, and an unexpected focus position does not identify the exact code responsible. Your public note can name the symptom and the conditions while leaving the cause for investigation.

If you discover an obstacle, preserve the useful part of the record. “I could not identify the focused control after applying the filter” is a specific observation. “Keyboard navigation is broken everywhere” is a broader conclusion. If you used the mouse after that point, label where the keyboard-only attempt ended instead of editing the interruption out.

Make the recording explain the task

A useful video should let a viewer follow the state changes without guessing which key was pressed. You can add a simple action caption or narrate the relevant step, then supply a text account beside the recording. Keep captions accurate and explain any cuts. An edited demonstration is not the same artifact as an uninterrupted check.

Avoid cursor movement that implies a mouse action when you are discussing a keyboard path. Keep the important control and focus indicator readable in the frame. If the recording cannot show them clearly, use a closer view or a carefully labeled still that explains the specific state. Do not add decorative effects that obscure the evidence.

The text note should stand on its own for a reader who does not watch the clip. State the task, conditions, obstacle or result and next check. A video thumbnail with “fixed accessibility” is not enough. It hides the scope and leaves other developers unable to tell which behavior you actually examined.

Report the change at the same scope as the check

Suppose the fictional developer makes a change intended to keep the focus location clear after filtering. A follow-up should repeat the same task and conditions before describing the observed difference. It should also say whether other relevant states, such as no matching sessions, remain unchecked. A successful path is not evidence about every path.

A careful update might say that the selected-session task was completed using the keyboard in the stated setup after the change. It should not announce full accessibility compliance from that one result. A broader assessment involves more questions, users and conditions than this article’s bounded demonstration covers.

Keep the earlier obstacle and the later observation distinguishable. A reader arriving after the fix should understand what changed and why the original note exists. If the old recording remains public, add a dated follow-up or link to the current explanation rather than leaving incompatible claims without context.

Ask peers for a specific review

A public build update can invite a peer to try the same task and report where their experience differs. Explain the required setup and ask them to use only information they can safely share. Do not require a personal booking or a real customer account just to comment on your public example.

Buildside describes founders sharing progress and offering useful observations; I build Buildside. That is the community context for a request such as, “Can you follow this focus sequence, and where does the explanation become unclear?” The request is about one piece of work, not an invitation to certify the whole product.

Before publishing the note, check that its strongest claim matches the artifact. If you only planned a walkthrough, call it a plan. If you completed one, state the conditions and result. If you stopped at an obstacle, show that limit. A precise account of one keyboard task gives other builders something useful to examine and gives you a clear next check.

Hey I'm Uriel Bitton. I write about building in public strategies and growing startups.

Subscribe for more stories on growing your audience by building in public.

Join us on Buildside: the social network for founders building in public.

Sources

DWP Accessibility Manual: keyboard testing

About Buildside and its founder

X-Robots-Tag Troubleshooting: Find the Noindex Rule Outside Your HTML

Uriel Bitton — Tue, 20 Oct 2026 13:18:32 +0000

To troubleshoot an unexpected X-Robots-Tag noindex rule, inspect the HTTP response delivered for the exact public URL. Compare its headers with the page's HTML and trace where each instruction was added. Editing an HTML meta tag will not remove a conflicting header supplied by another part of the delivery system.

The useful outcome is a documented explanation of the rule, its intended scope, and the response after a targeted correction. Treat indexing as a separate follow-up. A successful fetch gives you evidence about access and instructions; it does not guarantee that a search engine will select the page or cite it in an AI answer.

Understand the two places an instruction can live

Google documents both a robots meta tag in HTML and an X-Robots-Tag in an HTTP response. Its robots specifications also explain that conflicting rules use the more restrictive instruction. An index instruction in one location therefore does not cancel a noindex instruction elsewhere.

The header is useful for resources such as PDFs that cannot carry an ordinary HTML meta tag. It can also affect HTML pages. This is why a developer can see an apparently correct page template while the response still carries an exclusion instruction.

Keep the scope of this explanation clear. These are Google's documented indexing controls. Other services can interpret instructions differently, so verify the relevant provider before describing a header change as a universal repair for AI discovery. Noindex is an indexing instruction, not a way to protect confidential material.

Begin with the intended job of the URL

Before changing anything, confirm whether the resource should appear in search. A public product explanation, a draft preview, and a private customer export have different purposes. An exclusion can be intentional even when it surprises the person reviewing a report.

Ask the page owner which environment and audience the URL serves. Record the final public address and whether it is meant to be discoverable. If the content is private, involve the owner responsible for access controls. Removing noindex from a private resource is not a content optimization task.

Choose one representative affected page and one useful comparison page. The comparison should share enough of the delivery path to help isolate the difference. A marketing homepage and a file on an unrelated storage host may be a poor pair even when they belong to the same company.

Collect a response record someone else can reproduce

Record the requested URL, request method, timestamp, returned status, final destination, and all robots-related response headers. Keep the original observation before changing a configuration. Avoid copying cookies, authorization values, private query parameters, or unrelated personal data into the report.

Use the response associated with an actual page fetch. If a tool performs a different request method, state that limit and verify the method relevant to the incident. A screenshot of the rendered page is helpful context, but it does not show every instruction in the delivered response.

Inspect the HTML separately for robots meta tags. Save the relevant instruction and its scope. If your browser or inspection tool shows multiple response blocks because the request redirected, associate each block with its URL. Do not silently attribute every header in the chain to the final document.

Work through a hypothetical staging-rule leak

Imagine a fictional documentation site that intentionally excludes a preview environment from indexing. A shared delivery rule later applies the same noindex header to a public guide. The guide's HTML template still permits indexing, and its visible content loads normally.

This is an invented troubleshooting example, not an incident from HoneyWeRank, Uriel's work, or a customer account. It illustrates why the place where a page is written can differ from the place where a response instruction is added.

A writer inspecting the HTML might repeatedly change its meta tag and see no improvement. A developer inspecting the delivered header would instead ask which configuration adds it and which host or route matches that configuration. The corrective decision follows the rule's scope, rather than a guess about the article's wording.

The desired correction would preserve the preview environment's intended exclusion while changing only the unintended public match. Removing every indexing restriction across the service would go beyond the evidence and could create another problem.

Trace the instruction through the delivery path

Review the components that can modify the response in your own system. These may include an application, hosting configuration, proxy, or edge rule. Do not assume that the most familiar component produced the header. Use the available configuration and request evidence to locate the actual source.

Compare affected routes and hosts. Does the header appear on one file type, one directory, one environment, or every response? Does an otherwise comparable page lack it? Those differences help form a narrow hypothesis that the responsible owner can inspect.

Check for more than one source adding the instruction. Removing a header from the application may leave another copy upstream. The delivered response is the acceptance evidence. An updated configuration file only establishes what someone intended to deploy.

Where caching is involved, distinguish a fresh response from a previously stored representation using the tools and procedures your infrastructure supports. Do not assume that changing the origin immediately changes every delivered response. Record what you actually fetched and which delivery path it followed.

Keep crawl access separate from indexing instructions

Google says these instructions must be accessible to the crawler to be read. Blocking a URL in robots.txt can prevent Google from discovering a changed noindex instruction. Its noindex guidance explains this distinction.

Avoid treating robots.txt, noindex, and authentication as interchangeable controls. One manages crawl access, another addresses indexing, and actual access controls determine who can obtain protected content. Identify the outcome the owner wants before selecting a control.

For the hypothetical public guide, examine whether the relevant crawl path can reach the corrected response. A header fix behind a continuing crawl block leaves an unresolved discovery question. Record both conditions rather than declaring success after finding the right line in the configuration.

Verify a narrow correction before expanding it

Agree on the intended change with the service owner. Test the affected public guide and the comparison page, then inspect the preview environment whose exclusion should remain. This gives the change an explicit boundary.

Fetch the corrected public response and inspect both its headers and HTML. Confirm that the intended document arrived, that no other conflicting noindex instruction remains, and that the important text is present. Keep the timestamp and relevant response details alongside the original observation.

Also check the resource types covered by the rule. If the change was meant for one HTML route, verify that it did not unintentionally alter the policy for downloadable files or preview content. The specific checks should follow the actual rule, not a generic list of every URL the company owns.

If the delivered response still differs from the expected result, return to the evidence and scope. Repeatedly changing unrelated meta tags adds noise and makes the eventual explanation harder to defend.

Follow indexing and AI visibility as later observations

After the response is correct, use the search platform's available inspection and indexing evidence to follow its processing. Preserve the distinction between a fresh manual fetch and a crawler's recorded view. A stale report can describe an earlier condition without proving that the new response is wrong.

Google's AI features documentation says a supporting page must be indexed and eligible for a snippet in Search to qualify for its AI Overviews or AI Mode links. Eligibility still does not guarantee inclusion. Do not extend that requirement to every other answer engine.

For an AI visibility check, record the engine, prompt, date, search mode, exact linked page, and repeated observations. Track mentions, citations, recommendations, and visits separately. The technical repair restores an opportunity for discovery; the page still needs to answer a useful question.

Close with a cause, an owner, and a regression check

Write a short incident note describing the affected URL group, the source of the instruction, the intended policy, the correction, and the verified delivered response. Include the unresolved indexing or visibility questions without presenting them as a failed deployment.

For the fictional staging-rule example, a useful regression check would cover both the public host and the excluded preview host. Assign an owner to review that boundary when shared delivery rules change. The next investigator should be able to understand why the header exists and where its scope is controlled.

Hey I'm Uriel Bitton. I write about SEO, AEO, GEO, and helping brands get found in AI answers.

Subscribe for practical ways to grow your brand's visibility in search and AI answers.

Explore HoneyWeRank for SEO and AI visibility.

Sources

HTTP 429 and SEO: Make Crawl Throttling Temporary and Verifiable

Uriel Bitton — Mon, 19 Oct 2026 14:35:03 +0000

Treat an HTTP 429 response as a temporary capacity signal that you can explain and verify. Identify which rule produced it, confirm the request really belongs to the crawler you are investigating, and check that normal access returns after the limiting condition ends. A permanent wall of 429 responses is an access incident, even when a monitoring dashboard calls it successful bot protection.

For SEO and AI search work, the useful question is specific: can the relevant system fetch the public answer when it needs to? A lower error count in your browser does not settle that question. You need evidence from the same route, response layer, and recovery period.

What 429 tells a client, and what it does not

RFC 6585 defines 429 as too many requests within a period. The response should explain the condition and may include Retry-After. The standard does not prescribe how a server identifies a client or counts requests. It also says a 429 response must not be stored by a cache.

That leaves important choices in your implementation. A limit might apply to a route, an account, an address, or a shared pool. Before changing a threshold, write down what is counted and when the count resets. Otherwise, two engineers can discuss the same error while imagining different rules.

Do not read Retry-After as a promise that every crawler will return at that moment. It communicates a waiting period. Actual retry behavior belongs to the client. Verify each provider's current documentation before describing what its crawler will do.

Keep Google's documented behavior separate

Google's crawler documentation treats 429 as an overload signal and a server error. Persistent server errors can eventually affect indexed URLs, while successful responses allow crawling to increase gradually. Google explicitly warns against using 401 or 403 to control crawl rate.

This is documented Google behavior, not a rule for ChatGPT, Claude, Gemini, or every user-triggered fetcher. A rate-limit policy can affect several services, but the consequences need separate evidence. Do not label a Google crawl recovery as proof that an AI answer system can now retrieve the page.

The practical implication is modest: temporary protection needs an observable ending. A rule without a recovery check can quietly become a standing block.

Start with one request and its response layer

Choose a public page whose discovery matters, such as an integration guide or product explanation. Record the requested URL, method, time, observed status, relevant response headers, and the rule identifier if your infrastructure exposes one. Keep secrets, cookies, tokens, and personal query values out of the investigation record.

Then establish where the response originated. A 429 can be produced before an application handles the request. Compare the available edge, gateway, and application records rather than assuming the application generated every response. Missing application traffic is a useful clue, but it is not sufficient by itself to identify a particular upstream rule.

A user-agent string is a description supplied with a request, not independent proof of identity. Use the provider's supported verification process or your infrastructure's documented verified-bot signal where available. A manual request with a crawler name is a simulation. Label it that way instead of calling it a verified crawl.

A hypothetical incident worth distinguishing

Imagine a SaaS documentation site with a shared limit for public HTML and a high-traffic utility endpoint. A burst to the utility endpoint consumes the shared allowance. Requests for a quiet setup guide then receive 429, although the guide itself attracted little traffic.

This is an invented example, not an incident from Uriel's work or a customer account. Its purpose is to expose the difference between a busy page and a shared counting rule.

An engineer who inspects only the setup guide's request count may raise its route allowance without changing the shared pool. Another engineer may exempt every request claiming a search-bot identity. Neither action follows from the evidence. First determine whether the shared bucket, an upstream rule, or another constraint actually caused the response.

The narrow correction in this hypothetical case might be separating two workloads after reviewing capacity and abuse controls. It might instead be reducing the utility workload. The right choice depends on the system. An SEO objective does not justify removing protection without understanding why it exists.

Build a request evidence worksheet

Use one row for each observation. Keep the worksheet small enough that someone can reconstruct the event without searching several dashboards.

Request: URL path, method, timestamp, and the relevant environment.
Identity: claimed client and verification method, or explicitly unverified.
Decision: response status, rule identifier, counting scope, and available limit information.
Recovery: the later observation, returned status, and whether the expected document arrived.
Interpretation: what the record supports, plus what remains unknown.

A row saying only 'Googlebot blocked' mixes identity, cause, and outcome. A useful row says that a verified crawler request for a named path received a named rule's 429 response at a recorded time. If identity is uncertain, keep that uncertainty in the row.

This format also makes handoffs easier. A content team can identify the affected answer page, while an infrastructure owner can inspect the actual decision. Neither team has to infer the other's evidence from a screenshot of a percentage.

Test recovery without generating another flood

Plan a controlled check with the service owner. Establish the expected limit window, the permitted test rate, and the success condition before sending requests. Repeatedly hammering an already overloaded endpoint can make the incident harder to understand.

Inspect the body as well as the status. A 200 response containing an error page is not evidence that the intended article is available. Check that the main answer, navigation, and required public resources are present. Conversely, one successful browser load does not show that a separately classified crawler request follows the same path.

Where Retry-After is supplied, verify that it is meaningful for the condition being signaled. Check whether a later response still reflects the same limiting decision. Investigate any cached error behavior against the standard and your actual caching configuration rather than assuming the header alone repairs it.

Set a stopping condition for the test. The goal is a bounded explanation of failure and recovery, not a synthetic traffic benchmark. Preserve enough observations to compare the before and after states without collecting unnecessary private data.

Check the discovery outcome after access returns

Separate three findings in your report: the limiting rule changed, the relevant requests can fetch the intended page, and discovery or visibility changed afterward. These are different observations. The third does not follow automatically from the first two.

For organic search, review the platform's available crawl and indexing evidence over a suitable period. For an AI visibility check, record the prompt, engine, date, search mode, source URLs, and repeated observations. A linked citation, a brand mention, and a recommendation should have separate fields.

Avoid promising an indexing deadline or a citation increase. Other content and ranking factors remain in play. A clean response restores an opportunity to process the page; it does not decide whether the answer is relevant or worth recommending.

Close the incident with an owner and a trigger

A useful closure note states which pages were affected, which rule caused the issue, why the chosen adjustment was appropriate, and how recovery was verified. Include the responsible owner and the next condition that should trigger a review.

For the hypothetical shared-limit example, that trigger might be a change to the utility endpoint or a new protection rule affecting public HTML. The exact trigger should follow your architecture. A calendar reminder alone may miss the change that recreates the failure.

Keep the evidence worksheet with the incident record and link the affected public page. The next person investigating missing search visibility can then distinguish a content problem from an access problem without repeating the entire investigation. That is a more useful outcome than declaring every 429 an SEO emergency or accepting every blocked request as a security success.

Hey I'm Uriel Bitton. I write about SEO, AEO, GEO, and helping brands get found in AI answers.

Subscribe for practical ways to grow your brand's visibility in search and AI answers.

Explore HoneyWeRank for SEO and AI visibility.

Sources

Building in Public? A Sanitized HAR File Still Needs a Review

Uriel Bitton — Mon, 19 Oct 2026 14:05:50 +0000

To share a HAR file safely, start by deciding whether a public discussion needs the file at all. Prefer a small reproduction made with invented data, export a sanitized HAR when a diagnostic file is actually necessary, and review the exported contents before sharing. “Sanitized” describes a filtering step; it does not tell you that every remaining field is suitable for publication.

When you build in public, a useful debugging update can explain what you observed without exposing the request log behind it. Separate the public learning from the private diagnostic artifact. That gives other developers something concrete to discuss while keeping the amount of shared information tied to the actual question.

Know what the export promises

Chrome DevTools’ Network reference describes HAR as a JSON format for logged network requests. Its default sanitized export excludes the Cookie, Set-Cookie and Authorization headers. DevTools also offers sensitive-data export options. This guide uses the sanitized path; there is no reason to enable sensitive export just to make a public build update.

Those documented exclusions are useful, but they are a specific claim about headers. Do not extend them into a claim that an export contains no private information. Review other visible fields, including URLs, parameters, request content and responses. The information a particular capture contains depends on what the browser did during that capture.

The practical distinction is between a tool’s removal rule and your sharing decision. The first can be automatic. The second needs the context of the application, the intended recipient and the purpose of the discussion. If you cannot confidently inspect the file, ask for an approved support route or supply a smaller explanation instead.

Begin with the question the public post needs to answer

Consider a fictional developer building a form preview tool. A preview panel refreshes twice after a save. They want to show peers the sequence and ask whether their explanation of the behavior is clear. A production-session HAR would include far more activity than that question requires.

For a public post, the developer can describe the test conditions, the duplicate refresh they observed and the fact that the cause remains unconfirmed. A short conceptual timeline may be enough: save accepted, preview requested, second preview requested. Label it as a simplified account rather than an exact trace or a proven diagnosis.

If another developer needs more evidence, clarify which observation would help. They may need the request order or a status code, rather than all headers and bodies. A narrow request makes it easier to choose an appropriate artifact. It also prevents “send the HAR” from becoming the default answer to every debugging conversation.

Reproduce with a separate test context

Use a test account and invented content where you are authorized to do so. Keep the example small enough that you can explain every relevant input. For the fictional preview tool, a document called “Sample page” with a short dummy paragraph is more appropriate than a real customer’s unpublished document.

Begin recording as close to the relevant action as practical. Clear unrelated earlier requests from the Network panel before reproducing the issue, then stop once the needed behavior has appeared. This reduces unrelated material; it does not prove the result is safe. Review is still necessary even when the session was intended only for testing.

Record the conditions separately: browser version, product build if available, action taken and expected result. Do not add personal account details simply to make the report feel complete. If you cannot reproduce the problem without real private information, move the investigation to the service’s established private support process instead of forcing a public example.

Inspect the file you exported

Review the exported artifact rather than assuming it matches the rows you remember looking at. Check which hosts and requests are present. Look for unrelated services and activity outside the test. A recording can include requests you did not intend to discuss, even if your public screenshot shows only one selected row.

Read the remaining URL paths and query parameters. Then inspect any request and response content that the file contains, along with custom headers and other metadata. Look for information that identifies a person, an account or private work. Do not rely on a search for one familiar word as a complete review.

In this fictional case, the developer might discover a document title embedded in a path even though the standard sensitive headers were excluded. That is a hypothetical risk illustration, not a claim about a particular product. Recreating the capture with dummy content is preferable to casually editing a complex file and assuming every private value has been removed.

Keep the public artifact smaller than the investigation

The public update can say: “In this test, one save was followed by two preview requests. I have reproduced the sequence using dummy content. I have not yet established whether the second request causes the visible flicker.” This separates the observed request sequence from a causal claim that still needs work.

A useful accompanying image could be a carefully reviewed crop with abstract test values, or a simple diagram rebuilt from the relevant sequence. Explain which parts are simplified. Do not present a reconstructed diagram as an untouched capture. Readers should know whether they are looking at raw evidence or your explanation of it.

Avoid posting a full diagnostic archive as proof of being transparent. The amount of information disclosed is not a measure of how honestly you are building. A clear account of the question, the conditions and the remaining uncertainty can be more useful to a peer than a file they must inspect from scratch.

Use a private handoff when the file is needed

If a maintainer or support team actually needs a HAR, use the channel they specify and confirm what they need before sending it. Check the recipient and the artifact together. A file suitable for a particular private investigation is not automatically suitable for a public issue tracker, community thread or newsletter attachment.

Describe how the capture was made and which sanitization option you used. Do not claim it is risk-free. Also state whether it uses dummy data and whether the observed behavior matches the original problem. A clean synthetic capture may be safer to review, but a failure to reproduce the original symptom is a limitation worth reporting.

If you discover sensitive information after sharing, use the service’s established incident or support process. Removing a public attachment may limit further access, but it cannot establish that no one already copied it. Do not improvise a public investigation by asking others to download the file and tell you what they find.

Ask peers to review the explanation first

A founder community is useful for checking whether your public debugging note is understandable. Buildside’s about page describes sharing product progress and offering specific observations; I build Buildside. That context supports a request such as “Can you distinguish the observation from my current theory?” It does not require uploading a private diagnostic file to the community.

Give the reviewer the minimal public note and ask what conclusion it supports. If they infer that the cause is confirmed when you have only seen a repeated request, revise the wording. This is a check on the explanation, separate from a technical diagnosis. A well-written post can still contain an unproven theory.

Before publishing, make a final comparison between the question and the artifact. Does every included detail help someone assess that question? Can you explain the test without the file? Has the exact exported content been reviewed? A sanitized HAR can be a useful diagnostic tool, but careful public building starts with choosing what evidence needs to leave the debugging session.

Hey I'm Uriel Bitton. I write about building in public strategies and growing startups.

Subscribe for more stories on growing your audience by building in public.

Join us on Buildside: the social network for founders building in public.

Sources

Chrome DevTools Network reference: HAR exports

About Buildside and its founder

Write a Public Beta Quickstart That Ends With a Checkable Result

Uriel Bitton — Sun, 18 Oct 2026 13:50:57 +0000

A public beta quickstart should take a new reader from a stated starting condition to one result they can recognize. Name the version, supply safe sample input, explain the expected output and give the reader a clear point at which to stop or ask for help.

This makes your public progress post easier to act on. A visitor who follows the link should not have to reconstruct setup details from old comments or guess whether an unfamiliar screen means success.

The quickstart is a small agreement about one supported path. It does not need to document every feature, prove product demand or pretend the beta is finished. Its job is to help the reader attempt a real task and help you understand where that attempt becomes unclear.

Choose the first result before writing the setup

Pick a result that matters to the intended reader and is safe to reach in the beta. A successful login may be necessary, but it rarely explains why somebody would use the product.

For a fictional CSV-checking service, the first result might be a report that identifies an invalid date in a supplied sample file. The reader can compare the report with a known input. They are not asked to upload customer records to find out whether the product works.

Keep the path small. Importing a sample, viewing one issue and opening the matching row may be enough. A tour through settings, integrations and team administration belongs somewhere else unless one of those steps is required.

Write the result sentence before the instructions. It becomes the test for whether a setup detail is necessary now, useful later or unrelated to the path.

Put the supported version and access conditions at the top

State which release or beta build the guide describes, using an identifier your project actually exposes. Include the date of the last real verification. A recent edit date alone should not imply that somebody ran the instructions.

Name prerequisites before the first action. These may include an invited account, a particular browser, an installed dependency or a permission the reader needs. Don't hide a paid requirement or restricted invitation behind an apparently open start button.

If a prerequisite is outside the reader's control, explain how to recognize that situation. A person without beta access should know that the next step is to wait for an invitation, rather than repeatedly reset a password.

GitHub's README guidance identifies getting started and finding help as common README content. Your public beta needs those basics tied to the current path, whether the guide lives in a repository or on a documentation page.

Supply an input that makes the result understandable

Use an invented sample with enough detail to reveal the behavior you want the reader to inspect. Keep unrelated data out. Explain what is intentionally unusual about the sample so the output has a meaning.

In the fictional CSV service, a sample could contain a date formatted differently from the accepted pattern. The guide would identify that row as deliberately invalid and explain what the report should say about it.

Do not claim a generated file is representative customer data. It is a controlled teaching input. A later test with a user's own workflow answers a different question and may need different access and handling.

If the sample can be downloaded, use a stable link and describe the file. If the input must be copied, keep the formatting unambiguous. Check that a reader can tell where the sample ends and where the explanation begins.

Write actions and expected states together

For each meaningful action, describe what should appear next. This gives the reader a way to locate a failure without treating every pause as an error.

Use the labels that the current interface shows. “Choose the sample file, then select Check file” is clearer than a vague instruction to process the data. Avoid adding hypothetical button names to published documentation for a real product.

When a step can take time, use a verified expectation or describe the visible processing state. Don't invent an exact duration because it sounds reassuring. Explain what to do if the state persists beyond a limit your service actually supports.

A screenshot can help locate a control, but keep the written instruction usable without it. The image may be cropped on a small display, and a reader should still understand the action and its intended result.

Walk through a fictional guide without pretending it was tested

Consider a draft quickstart for the invented CSV service: create an account, upload a file and inspect the report. Each instruction sounds reasonable, but the reader has several unanswered questions before reaching the result.

Which account can access the beta? What file is safe? Does a blank report mean every row passed, or did the upload fail? Where should the intentionally invalid date appear? This example describes a proposed guide, not a tested application or runnable tutorial.

A stronger draft starts by naming the beta build and the invited-account requirement. It links to the invented sample, explains the one deliberate date issue and says that the completed report should show that issue against the corresponding row.

It then gives a stop condition: once the reader has matched the issue to the sample row, the quickstart is complete. Correcting a real dataset is outside this first path. That boundary prevents a teaching exercise from quietly becoming a request for production work.

Make recovery specific to the point of failure

Provide a small help path beside a likely blocked step. An access problem, a missing sample and an unexpected report are different states; a single instruction to try again leaves their causes mixed together.

Ask the reader for the minimum useful information when they report a problem. A build identifier, the step and the visible error can help. Don't ask them to paste secrets, account tokens or private files into a public issue.

For the fictional report mismatch, the guide can ask whether the supplied sample was used unchanged. If the reader used another file, the output may reasonably differ. The question locates the uncertainty without blaming the person.

If your beta cannot recover safely from a state, say where to stop. Do not recommend deleting work, changing permissions or repeating a consequential action merely because those steps might make the screen move forward.

Verify the guide as a new reader would encounter it

When the real product is available, follow the published path with an appropriate clean account or environment. Use the linked sample and the current guide. Record what you actually checked, including the version and any untested branch.

Separate a documentation check from a product test. Reaching the described output shows that this path matched the guide under those conditions. It does not show that a new customer found it easy or that the product meets their broader need.

Ask a relevant reader to attempt the task without coaching when you need to learn about comprehension. Note the point where an explanation was required. Improve the guide or the product based on the issue you observed.

Never write that you ran a clean-start test if you only reviewed the prose. A clearly marked unverified draft is more useful than a confident guide with an invented verification history.

Use the quickstart in your public progress update

Link directly to the supported path and state the intended reader. Explain the result they can attempt, the limits of the beta and the kind of feedback that would help. Keep the invitation separate from claims about demand or reliability.

Buildside is a place for founders to share work and questions. I founded it. A public update can give peers a precise documentation question, such as whether the guide makes the first successful result clear.

Keep the guide current when that path changes. Update the supported version and repeat the relevant check rather than leaving earlier readers to discover that a button or prerequisite disappeared.

Open your current beta instructions and find the last line. If it says explore the product, replace that vague ending with one observable result and a clear stop point. Then check whether every earlier step helps the reader reach it.

Hey I'm Uriel Bitton. I write about building in public strategies and growing startups.

Subscribe for more stories on growing your audience by building in public.

Join us on Buildside: the social network for founders building in public.

Sources

About the repository README file — GitHub Docs

Buildside — public product description

HTTP 304 and SEO: Check the Validator When a Page Changes

Uriel Bitton — Sun, 18 Oct 2026 13:27:20 +0000

A 304 response is appropriate when a conditional request shows that the client's stored representation is still valid. When a public page changes, verify that its HTTP validators reflect the change and that a request using the old validator receives the current representation. Do not diagnose every 304 as an SEO error.

This is a focused review for developers responsible for public documentation or product pages. It checks whether your delivery path tells a client the truth about a changed document. It does not prove when a search engine will revisit, index, or cite that document.

Separate a page date from an HTTP validator

A visible “updated” date is content shown to the reader. An HTTP validator helps a client determine whether the representation it already holds can still be used. They can refer to related events, but they are not interchangeable controls.

Two common validators are an ETag, which is a server-provided tag for a representation, and Last-Modified, which gives a modification time. Their request counterparts include If-None-Match and If-Modified-Since. Review the actual response headers instead of inferring them from a date in the page footer.

Keep the scope narrow. You are checking one public page's representation under recorded request conditions. A response for a signed-in dashboard, a different language, or another content encoding may not be the same representation.

Know what the status means

According to MDN's 304 documentation, a 304 tells a client that retransmitting the requested resource is unnecessary after a qualifying conditional GET or HEAD request. A 304 response does not contain a body. The client uses its stored representation.

Google's crawler documentation describes support for ETag/If-None-Match and Last-Modified/If-Modified-Since. It notes that Googlebot supports caching during recrawls and that individual crawlers can use caching differently. Do not generalize that documented Google behavior to every AI agent.

The practical question is whether the condition was evaluated against the correct current representation. A high count of 304 responses alone cannot answer that. You need the request condition, the response, and the content version being checked.

Prepare a small two-version example

Use a safe review environment or an approved change on a page you control. Do not test by changing unrelated production content. The following example is hypothetical and describes a method, not a test performed on a live customer's site.

Version A of a public guide says an export contains all columns. Version B adds a verified option to choose columns. Record one sentence unique to Version B so you can recognize the current response body without relying only on a timestamp.

Before the change, record the observed URL, relevant request headers, status, validator values, and the visible content marker. After the change, repeat the request through the normal public delivery path. Keep the same relevant conditions so a different response variant does not confuse the comparison.

A useful review note should identify whether a CDN or proxy sits between the client and the origin. You do not need to assume it is broken. You need enough context to locate where an old or incorrect response could have been introduced.

Check the unchanged case first

Obtain the current page normally, then make the appropriate conditional request using the validator you observed. If the representation has not changed and the request qualifies, a 304 can be the correct result. Record it as the unchanged case.

Do not copy a validator from an unrelated request or invent one that merely looks plausible. The value must come from the response you are comparing. Keep quotation marks and other meaningful formatting intact when your approved testing tool submits it.

Use a GET when you need to inspect the body of a changed response. A HEAD response can help inspect headers, but it does not give you the full document to compare. Choose the request that answers the specific check you are performing.

Check the changed case with the old validator

After Version B is available, submit a conditional request using Version A's recorded validator. Compare the result with the current content. The important acceptance check is that the client can obtain the changed representation when its stored one is no longer valid.

If the response indicates unchanged content while the representation really changed under the same conditions, collect the evidence before editing server settings. Include the old validator, current public response, request conditions, and the sentence that distinguishes the versions.

Repeat a normal request through the same path. If it also returns Version A, the problem may be that the changed document has not reached that delivery path yet. If it returns Version B while the old validator still produces an unchanged result, the conditional handling deserves closer inspection.

Do not solve an unexplained mismatch by disabling all caching. First identify which layer produced the result and how its validators are generated. A narrow correction is easier to assess than a broad behavior change whose effects are unknown.

Avoid using timestamps as decoration

If your implementation emits Last-Modified, make sure the value follows the HTTP date format and represents a meaningful modification time. Google's crawler guidance specifically calls out formatting requirements. A display date copied into a header without validation is not a reliable implementation.

Do not generate a new modification time on every request merely to make a page seem fresh. That defeats the purpose of an unchanged-content check. Likewise, a permanently frozen value can hide a real change if it no longer describes the representation.

For an ETag, review how the tag changes when the relevant representation changes. The implementation details depend on your server and delivery setup. Treat the tag as part of that setup rather than choosing arbitrary values in an article example and copying them into production.

Test one variation that matters

If the page is served in multiple languages, review the intended language version separately. If the response varies with a relevant request header, record it. You need a consistent comparison, not an average of different documents that happen to share a URL.

Inspect the path readers and crawlers normally use. An origin-only test can miss a stale edge response. An edge-only test can show the symptom without identifying the origin's current output. Use the smallest set of checks that distinguishes those possibilities.

Keep unrelated concerns separate. Correct validators do not repair a wrong canonical, missing internal link, or unsupported product claim. They help a client reuse a valid representation or obtain a changed one. Each discovery or content problem still needs its own evidence.

Write a useful acceptance record

A clear result contains the observed URL, test time, request conditions, Version A and Version B markers, recorded validators, and the outcome of the unchanged and changed cases. Store only information appropriate for the review; avoid including private headers or credentials in a public issue.

Ask another developer to repeat the two cases using the same approved process. If the result differs, record the condition that changed rather than selecting the response that fits the initial theory. A reproducible mismatch is more useful than a dramatic screenshot of a status code.

Finish with a bounded statement: the reviewed page returned the expected current representation under the tested conditions, or a specific mismatch remains. That supports a concrete fix. It does not establish a ranking improvement, a recrawl deadline, or an AI citation outcome.

Hey I'm Uriel Bitton. I write about SEO, AEO, GEO, and helping brands get found in AI answers.

Subscribe for practical ways to grow your brand's visibility in search and AI answers.

Explore HoneyWeRank for SEO and AI visibility.

Sources

MDN: 304 Not Modified

Google: Overview of crawlers and fetchers, including HTTP caching

Your Public Beta Needs a Bug Report a Stranger Can Reproduce

Uriel Bitton — Sun, 18 Oct 2026 13:15:04 +0000

Give public beta testers a short way to report what they tried, what they expected, and what happened. Then turn that report into a separate developer reproduction note with a known starting state, exact steps and the environment you checked. Don't make the tester do your whole debugging job.

Building in public can bring people to an unfinished product. It also creates a handoff problem: a useful comment such as “the import stopped” is not yet enough for somebody else to repeat the failure. Treat the comment as the beginning of a report, rather than proof that the reporter did something wrong.

The workflow below uses two linked records. One captures the tester's observation with little effort. The other records the developer's investigation. Keeping those jobs separate helps you preserve what was actually reported while adding the detail needed to act.

Ask for the smallest useful first report

Start with the task, the action that failed, the visible result and the expected result. Give the tester a clear route to send those details, including a private route when the information should not be public.

Ask for environment details the person can reasonably provide. “Which browser and device were you using?” is accessible. “Attach a sanitized request trace” may be too much for somebody who volunteered to try an invoice tool.

Make screenshots optional when a plain description will do. A screen can contain client names, file paths, email addresses or other information that does not belong in a public discussion. Explain what to leave out before asking for an attachment.

Don't collect every possible field just because your tracker supports it. If a version is already clear from the beta link, you can add it yourself. The first report needs enough information for the next question, not a complete diagnostic archive.

Keep the reporter's observation separate from your diagnosis

Write down what the tester saw before adding a theory about why it happened. “The spinner stayed visible after selecting Import” is an observation. “The server timed out” is a diagnosis that needs evidence.

If the reporter supplies a theory, preserve it as their suggestion. Do not silently turn it into the ticket's confirmed cause. A useful investigation can begin with an incomplete description without making the description more certain than it is.

Ask a narrow follow-up when needed. You might need to know whether the person started from a new project or reopened an existing one. That distinction is easier to answer than a general request for more information.

Keep the original report linked to your investigation note. When you later reproduce a similar symptom under different conditions, you will need to check whether you found the same problem or a different one.

Use a report format people can understand

GitHub's issue-form documentation shows examples that collect current behavior, expected behavior, reproduction steps and environment. It also supports different field types and validation. Those are tools for structuring a report, not a reason to require every field from every tester.

For a small public beta, a plain form or message can ask: what were you trying to do, where did you begin, which action changed the screen, what appeared, and what did you expect instead?

Let the person say that they do not know an answer. A guessed software version is less useful than an unknown one. You can often narrow the environment later without asking them to become familiar with your release process.

If you use a public issue tracker, say that before submission. A tester should not discover that their attachment is public only after sending it. Keep account-specific investigation in an appropriate private support route.

Build a developer note from a known starting state

Once you have the initial report, write the state needed to repeat the attempt. Include the relevant build, browser, account role and sample data. Add only details that help distinguish this attempt from a different one.

The starting state can matter as much as the clicks. An empty workspace, an existing import mapping and a previously failed upload are different conditions. If you reset the product before testing, record that reset.

Use one action per step and name the visible control. “Open a new workspace, select the sample file, then press Import” is easier to inspect than “try uploading as usual.” State the result at the step where the behavior diverges.

Keep an exact error message when it is safe to do so. Preserve relevant punctuation and wording. Remove secrets and private identifiers rather than pasting an entire log into a public ticket.

Work through a fictional CSV import failure

Imagine a fictional beta product that imports a list of workshop registrations. A tester says that importing a file stops at the mapping screen. They expected to see a confirmation showing the imported rows. This is an invented example, not a report from a real beta.

The developer asks whether the file has a header row and whether a mapping was already saved. The tester says it has a header and that they reused yesterday's workspace. The developer now has two conditions worth checking without assuming either one is the cause.

The first reproduction note uses a fresh workspace and a small invented file with name and session columns. The import succeeds. Record that result as a successful attempt under those conditions, rather than closing the original report as user error.

The next attempt starts with a saved mapping, then imports a file with one column renamed. If the failure appears there, record the exact sequence and the visible difference. You have narrowed a condition; you have not yet proved the underlying cause.

Say unreproduced when you have not reproduced it

An unreproduced report is a legitimate state. It means the investigation has not repeated the reported behavior under the conditions checked. It does not mean the person imagined it or that the product is reliable in every environment.

List the attempts that matter and the next missing detail. In the fictional example, you might still need to learn whether the original file contained an empty column. That is a concrete question the tester can answer without providing private registration data.

Avoid a long sequence of speculative requests. Each new question should help distinguish plausible conditions. If the reporter is no longer available, preserve the gap and decide what you can check independently.

When a workaround exists, describe the conditions you actually verified. “Creating a new mapping worked with our sample file” is more accurate than “just reset everything.” Be clear if the workaround would remove saved work or impose another cost.

Return a useful status to the public thread

If the report began under a public beta invitation, return with a short status that does not expose the private investigation. Say whether the issue is reproduced, still being checked, or fixed in a named available build.

Do not publish a cheerful fixed message when the change is only in a local branch. Describe the state precisely. A fix that exists but is not available to testers has not yet repaired their experience.

Invite a recheck only when the relevant version is available and participation remains optional. Give the original steps and explain which behavior should now differ. The tester should not have to rediscover the entire report to help again.

Buildside is a place for founders to share progress and questions. I founded it. A public update can explain the investigation and its limits, while the detailed report stays in the place suited to its data.

Measure the quality of the handoff

The useful question is whether another developer can reach the relevant state and inspect the claimed failure. Counted fields and long attachments cannot answer that on their own.

Before closing the ticket, ask somebody to follow the reproduction note without your verbal explanation if you have that help available. For a solo project, return to the note after a break and check which steps depended on memory.

Record what remains untested after a fix. One repaired sequence does not establish that every import combination works. Keep the scope of the public claim close to the scope of the check.

Before your next public beta invitation, try your own reporting route. Make a small invented report, turn it into a reproduction note, and identify the point where a stranger would need to ask what you meant.

Hey I'm Uriel Bitton. I write about building in public strategies and growing startups.

Subscribe for more stories on growing your audience by building in public.

Join us on Buildside: the social network for founders building in public.

Sources

Syntax for issue forms — GitHub Docs

Buildside — public product description

Your Public Beta Needs a Bug Report a Stranger Can Reproduce

Uriel Bitton — Sun, 18 Oct 2026 00:00:43 +0000

Ask for the smallest useful first report

Keep the reporter's observation separate from your diagnosis

Use a report format people can understand

For a small public beta, a plain form or message can ask: what were you trying to do, where did you begin, which action changed the screen, what appeared, and what did you expect instead?

Build a developer note from a known starting state

Keep an exact error message when it is safe to do so. Preserve relevant punctuation and wording. Remove secrets and private identifiers rather than pasting an entire log into a public ticket.

Work through a fictional CSV import failure

Say unreproduced when you have not reproduced it

Return a useful status to the public thread

Measure the quality of the handoff

The useful question is whether another developer can reach the relevant state and inspect the claimed failure. Counted fields and long attachments cannot answer that on their own.

Record what remains untested after a fix. One repaired sequence does not establish that every import combination works. Keep the scope of the public claim close to the scope of the check.

Hey I'm Uriel Bitton. I write about building in public strategies and growing startups.

Subscribe for more stories on growing your audience by building in public.

Join us on Buildside: the social network for founders building in public.

Sources

Syntax for issue forms — GitHub Docs

Buildside — public product description

Pagination SEO: Make Page Two a Real, Crawlable URL

Uriel Bitton — Sat, 17 Oct 2026 23:59:18 +0000

For pagination SEO, give each result page a real URL and link to the sequence with ordinary crawlable links. Check that page two opens directly, shows its own results, and can lead to later pages. A “Load more” button alone does not establish that a crawler can follow the collection.

This matters when useful public pages sit beyond the first screen of a directory or archive. Before adding more content, test the path that leads to the content you already have. The goal is reliable discovery of relevant pages, not making every possible filtered view eligible for search.

Define the collection you intend to expose

Start with one public collection, such as a directory of integration guides. Write down which detail pages belong in it and which views serve a real reader need. A pagination review should not quietly turn thousands of arbitrary sort and filter combinations into a search strategy.

Use a small hypothetical fixture for the review: 23 directory entries, ten results per page, and three result pages. Number the entries internally so you can compare the sequence. These are test values, not a claim about any live website or an engine's preferred page size.

Decide what a complete pass through that collection means. A reader should be able to reach every included detail page, understand where they are, and move through the list without losing the selected context. Those requirements give the review a clear finish line.

Check the documented discovery behavior

Google's pagination guidance says its crawlers generally follow links in anchor elements with href attributes. They generally do not click buttons that trigger more results. The guide recommends crawlable links between pages in a sequence and a unique URL for each page.

The same guide says each paginated page should have its own canonical URL, rather than pointing every page back to page one. It also advises against using URL fragments for page numbers. Google no longer uses rel="next" and rel="prev" as pagination signals.

Keep the scope of that evidence clear. These are Google's documented practices. They do not establish how every AI crawler handles every framework. A public link path is a sound thing to test, but it is not proof that an answer engine will cite an entry.

Open page two in a fresh tab

Use the actual page-two link from the live interface. Open it in a fresh tab and copy the observed URL into your review notes. Do not start from a URL you invented because the route looks predictable. You are checking what the product actually exposes.

A path such as /guides?page=2 can identify the second page. The exact route format is less important than whether it is stable and represents the intended view. Confirm that the second page shows entries 11 through 20 in the hypothetical fixture, with the same relevant collection context.

Now reload that URL. Try it without first visiting page one. If the results only exist after earlier clicks or session state, the URL is not yet a dependable representation of page two. Record the visible result and the condition that caused it to fail.

Check the rendered title or page label too. A person arriving directly should know this is a later part of a collection. They should have a way to return to the beginning and enough context to understand what the collection contains.

Inspect the path to later entries

From page one, inspect the real next-page control. Is it a link with a destination, or only a button that runs an event handler? Then inspect the control on page two. The first link being crawlable does not establish that the rest of the sequence is connected.

For a load-more interface, ask whether a usable link-based route exists alongside the interaction. You can preserve the reader's preferred browsing experience while giving result pages stable destinations. Review the actual implementation instead of treating a visual button label as evidence.

Follow the sequence to page three. In the fixture, it should contain entries 21 through 23. Open one detail page from each result page. Confirm the links lead to the intended public content rather than a placeholder, sign-in wall, or unrelated redirect.

Record a short path in the review: collection start, second page, last page, and a detail page from each. This makes the finding reproducible. “Deep pages seem hard to find” is much harder for another developer to investigate.

Test the end of the sequence

The final page deserves a separate check. It should not offer a next link that returns the same results forever. A misleading endless sequence wastes a reader's time and makes it harder to tell which URLs represent distinct pages.

Test an out-of-range page using your own site's approved development or review process. Decide with the team what a valid response should be when a requested page no longer exists. The important point is to avoid silently presenting an unrelated page as if the request succeeded.

Also test what happens after the collection changes. If a new entry moves existing items to later pages, can readers still find the relevant detail pages through stable item links? Pagination is a way into the content; it should not be the identity of the content itself.

Review URLs, canonicals, and sort order together

Read the canonical URL on each sampled result page and compare it with the view shown. If every later page declares page one as canonical, record that as a mismatch with Google's pagination guidance. Include both the observed page URL and declared canonical in the issue.

Check that the sort order is defined well enough for the sequence to make sense. If two entries share a sort value, a consistent tie-breaker can prevent confusing movement during a review. This is an implementation recommendation for predictable lists, not a documented search ranking factor.

Keep sorting and filtering separate in your notes. A page number identifies a position within a particular collection state. Losing a required filter when moving to page two changes the question the page answers. Test one supported filtered sequence when that behavior matters to the reader.

Write a fix request another person can verify

A useful issue includes the starting URL, the control used, the destination observed, the expected entries, and the actual result. Add a screenshot when it clarifies the failure. Avoid an issue title such as “Fix SEO” when the defect is a missing destination link.

State an acceptance check in ordinary terms: opening the observed second-page URL directly shows the intended entries; a crawlable link leads to the next valid page; the final page stops the sequence; each sampled detail page opens correctly. The implementation can then be reviewed against visible behavior.

After the fix, repeat the same small sample. Expand the test only if a new failure suggests a wider problem. A focused collection review is easier to maintain than a huge checklist nobody repeats after a routing change.

Keep the outcome honest. You can verify that the pages and links work and that they follow the documented Google guidance you checked. Indexing, organic ranking, and AI citations require separate observations. Making page two findable removes a discovery problem; it does not promise what any engine will do with the content.

Hey I'm Uriel Bitton. I write about SEO, AEO, GEO, and helping brands get found in AI answers.

Subscribe for practical ways to grow your brand's visibility in search and AI answers.

Explore HoneyWeRank for SEO and AI visibility.

Sources

Google Search Central: Pagination, incremental page loading, and SEO

Build in Public Without Breaking Trust: Write the Migration Note First

Uriel Bitton — Fri, 16 Oct 2026 15:32:13 +0000

Before announcing a breaking product change in public, write and rehearse the migration note. Explain who is affected, what stops working, how to move to the new behavior, and what to do if the move fails. If those instructions are unclear, the release announcement is early.

Building in public makes the change visible to people who are curious about your work. Some of them also depend on the current behavior. A good explanation respects both groups, with the affected user's next action taking priority over the founder's launch story.

Identify the behavior that people depend on

Start with the current workflow, not the implementation diff. A database column can change without affecting a user. A small change in an exported file can break somebody's carefully maintained import.

Write down what a person can do today and what they will be able to do after the release. Include defaults, permissions, saved settings, file formats, and integrations where they matter. These are prompts for an impact check, not a claim that every change touches all of them.

Ask who relies on the old behavior. You may have evidence from support conversations, documentation, or authorized product records. If you don't know, state that uncertainty and investigate before treating the change as harmless.

A feature's low visible usage does not prove that nobody depends on it. A monthly export may matter a great deal to the person who uses it once a month.

Separate a changelog entry from migration instructions

Keep a Changelog recommends a curated record for people and explicitly includes changes, deprecations, and removals. That is a useful foundation. A list of changes still needs instructions when a reader must act.

A changelog entry tells the reader what changed in a release. A migration note explains how to preserve or deliberately change an existing workflow. A public founder update can then explain the reason and the tradeoff.

These documents can link to each other without repeating every detail. Keep one maintained place for the actual steps. A social post is a poor location for the only copy of instructions that may need correction.

Don't call a change an improvement for everyone if a known group loses something. State the affected behavior plainly, even when the new design is better for the product's main use case.

Rehearse a fictional CSV migration

Imagine a fictional scheduling SaaS that exports appointment data. The existing export puts the customer's displayed name in the first column. A planned export adds a stable booking identifier first and moves the name to the second column.

That sounds minor until an existing spreadsheet reads the first column as a name. A founder who tests only whether the new file downloads will miss the broken handoff.

The migration note should identify the affected group: people whose saved imports select fields by position. It should explain the new layout and provide an example file with invented data. It should distinguish that group from readers who open each export manually.

This is an illustrative scenario, not a report about Buildside or a real customer's system. Its purpose is to show how a public announcement can be accurate about a feature while still omitting the user's most important task.

Test the old and new path with the same example

Prepare an example that works through the old workflow. Save the expected result. Then use equivalent invented input through the proposed new workflow and inspect the result at the receiving end.

In the scheduling example, the relevant finish is a correctly populated spreadsheet. The download completing is only an intermediate step. Check whether names, identifiers, times, and empty values arrive where the documented steps say they will.

Keep a comparison path where the old workflow remains unchanged. That helps distinguish a problem introduced by the migration from a problem that already existed in the example.

Record what you checked and what you didn't. One spreadsheet application or one importer is a bounded test. It is not proof that every downstream tool will accept the new format.

Write instructions a reader can follow without your help

Describe the starting condition before the first action. A person needs to know whether these instructions apply to their account, export version, or saved setup.

Then explain the actions in the order the user will take them. Use the exact visible names that exist in the shipped interface. If a step requires an option you have not implemented, the note has found unfinished work.

Include a check after the change. “Import one example and confirm the name is in the name field” is more useful than “Make sure everything works.” A reader should know how to detect a failed migration before relying on the output.

Have someone unfamiliar with the change read the instructions against the test setup. If you have to explain a missing step aloud, revise the written version. Report that review as completed only if it actually happened.

Decide what happens when the migration fails

A useful note needs a recovery path that the product can support. That might be returning to the earlier format, keeping the old workflow temporarily, or contacting a defined support route before proceeding.

Don't promise a rollback just because it would make the announcement reassuring. Some changes cannot be reversed cleanly after new data is written. Describe the actual boundary and make the implementation decision before publishing the instructions.

For the fictional export, the founder could choose to keep the original layout as the default while offering the new layout separately. That is one possible design, not a universal requirement.

The alternative might be a carefully announced replacement with a clear transition period. Which choice fits depends on the evidence, the cost of supporting both paths, and the impact on people who rely on the old one.

Announce the user action before the founder story

Open the public release post with the affected behavior and any required action. Place a link to the maintained migration note where a reader can find it immediately.

Explain the reason after the reader knows what to do. You might describe why stable identifiers solve a recurring import problem. Avoid presenting an internal cleanup as a customer benefit without explaining the connection.

Be careful with availability. A release note drafted in advance should not imply that the new behavior is already live. When access varies, say which version or group can use it.

A screenshot can show the new export option, but it cannot prove that an existing importer still works. Use the screenshot to explain the interface and the rehearsal to evaluate the workflow.

Use public feedback to find missing cases

Sharing the migration explanation with relevant peers can reveal assumptions. Someone may notice that the note omits timezones, saved mappings, or the handling of blank fields.

Buildside connects founders sharing work in public. I founded it. A useful question for other builders is whether the proposed instructions make the affected workflow clear.

Peer review complements checks with actual intended users. Another developer may understand the format while missing a business-specific dependency. Keep that distinction visible when describing what the review established.

Don't ask people to upload private exports into a public thread. Provide an invented example and a route for reporting a problem without exposing real customer information.

Update the note when reality disagrees

After release, keep the migration instructions connected to the version they describe. If you discover a missing case, add a dated correction and explain its practical effect.

Return to the public announcement when a correction changes the user's next action. Readers who saved the first post should have a clear route to the current instructions.

Review support reports for misunderstandings as well as defects. A technically correct change can still fail because the instructions assumed a setup that the reader did not have.

Before your next public release, try writing the migration note first. A difficult paragraph often points to a difficult transition. Solving that transition gives you a more useful thing to announce.

Hey I'm Uriel Bitton. I write about building in public strategies and growing startups.

Subscribe for more stories on growing your audience by building in public.

Join us on Buildside: the social network for founders building in public.

Sources

Keep a Changelog

Buildside — public product description

SaaS Docs Migration: Test the Old-to-New URL Map Before Launch

Uriel Bitton — Fri, 16 Oct 2026 13:35:25 +0000

Before moving SaaS documentation to new URLs, test the old-to-new mapping against the answer each old page provided. A successful redirect is only one part of the check. The destination must also contain the relevant documentation, use the intended URL, and work for a reader arriving from an old link.

Treat the mapping as a release artifact with an owner and expected results. Do not leave it as a spreadsheet that someone reviewed once. A route can return a valid response while taking a developer to the wrong product version or a generic docs homepage.

The workflow below is an editorial and engineering test plan for a fictional docs migration. The paths are examples, not observed results from a real site.

Define what is moving

Suppose a company moves guides from /help/ to /docs/. Its team also wants to rename sections and combine a few articles. These are separate decisions. Record the path change, the content change, and any version change in separate columns so a reviewer can tell what each mapping means.

Start with a written scope: which hostnames and paths are involved, which product versions remain supported, and which pages must stay at their current addresses. Include images and downloads when they are part of the documentation experience. A route inventory that ignores linked examples can leave an otherwise readable guide broken.

Google's site-move documentation recommends preparing a URL mapping and testing the new site before moving. It also covers permanent redirects and monitoring old and new URLs. Use that as the search foundation, then add checks for your application's actual docs behavior.

Build an inventory with reasons

Combine the current published page list with useful evidence from your own analytics, link records, and server logs. Note which source found each URL. A page with little recent traffic can still be linked in a customer setup guide or an old SDK readme, so traffic alone is not a deletion rule.

Give every old URL a disposition: unchanged, moved, merged into a relevant replacement, or deliberately removed. Assign an owner to unresolved rows. A blank destination should mean “needs a decision,” rather than quietly becoming a redirect to the homepage.

Record why the chosen target is useful. For example, /help/export-csv might map to /docs/reports/export because that page still explains the CSV export task. The reason is content correspondence. It is not merely that both paths contain a reporting word.

Write the expected reader outcome

Add an acceptance note to each important row. For the export guide, it might say that a reader can find the CSV steps for the current product and identify the plan limitations. This note gives the content reviewer something more precise than a green status code.

Separate old-version documentation from current instructions. If an old URL served version one, sending it to a version two page may be confusing even when the feature has the same name. Decide whether to preserve an archive, explain the version boundary, or provide a relevant transition page.

Do not manufacture a replacement when the old task no longer exists. Document the removal decision and the intended response. Search preservation is not a reason to promise an unsupported feature or disguise an unrelated landing page as documentation.

Check redirects before following them

For each moved route, first inspect the initial response and its destination. Then follow the route to its final page. These checks answer different questions: whether the old route has the intended move response, and whether the full journey reaches the expected content.

Flag loops, unnecessary intermediate hops, unexpected host changes, and destinations that fall back to a generic page. Test at the layer that serves public traffic. A framework route can look correct locally while a hosting rule takes precedence in the deployed environment.

Include representative variants only where they exist in your inventory or routing rules: trailing slashes, encoded characters, case differences, and meaningful query parameters. Do not invent a huge matrix of hypothetical URLs. Use the actual system's behavior to choose the cases that could change the reader's destination.

Test rule collisions

A broad redirect rule can override a specific mapping. In the fictional move, a rule that sends everything under /help/ to /docs/ might swallow the dedicated export target. Test a specific route, a nested route, and an intentional exception against the final deployed rule order.

Pay special attention to routes created after the inventory was collected. Freeze the relevant publishing changes briefly or establish a clear process for adding new rows. Otherwise, the team can launch a map that was complete on Monday and incomplete by Friday.

Review two-way conflicts as well. The old server should not redirect to a new path that redirects back through a compatibility rule. Keep the intended destination written in the test record so a chain cannot pass simply because it eventually returns some successful page.

Verify content and page signals together

At each target, check the visible heading, relevant instructions, product version, navigation, and essential assets. A matching title alone is weak evidence: an empty article template can still display the correct title. Ask a reviewer to complete the original task using the destination page.

Google's migration guidance also covers updating internal links, canonicals, and sitemap entries to the new URLs. Check those signals against your approved destination list. A move is harder to reason about when the navigation uses a new path but the page identifies an old path as preferred.

Keep these checks distinct in the release report. “Redirect passes” should not imply “content reviewed.” Give route handling, content correspondence, and page signals their own outcomes. That makes failures easier to assign and prevents one green column from hiding a missing review.

Set launch gates that someone can act on

Classify failures by their effect on a real task. A broken authentication setup guide may block the release. A cosmetic spacing issue on a low-use archive page may have a different owner and deadline. Agree on the classification before the launch review so the team does not improvise under time pressure.

For each blocker, record an old URL, expected target, actual result, environment, test time, and owner. Include a short reproduction note. A report saying “redirects broken” is much less useful than a row showing the exact route and incorrect destination.

Retest a fixed rule against the cases it can affect. Do not only recheck the single URL that first failed. A change to a broad path matcher can repair one destination while damaging several exceptions.

Prepare the recovery plan

Save the approved map and the released routing configuration together with the release record. Identify who can correct a mapping and who can decide to pause the move. A recovery plan should explain the action available, rather than assume that restoring yesterday's files will reverse every external effect.

For a large move, consider a limited section when that fits the architecture and business constraints. Keep the limitations clear: a quiet section can validate routing mechanics without representing the entire site's search response. It is a test of a defined scope, not proof that every later page will behave the same way.

Monitor the old routes after launch

Review requests to old URLs, redirect failures, unexpected destinations, and reports from readers. Compare the old and new page groups in your search and analytics tools. Annotate the move date and any later fixes so the team can interpret changes with context.

Do not promise that a migration will preserve every position or settle within a fixed number of days. Also keep AI citations separate from routing tests. A correctly mapped page can remain uncited, and an old citation can still point to a route you need to support.

The practical release question is whether someone following yesterday's documentation link can reach today's relevant answer. Build the map around that outcome, test the actual journey, and keep the evidence with the release.

Hey I'm Uriel Bitton. I write about SEO, AEO, GEO, and helping brands get found in AI answers.

Subscribe for practical ways to grow your brand's visibility in search and AI answers.

Explore HoneyWeRank for SEO and AI visibility.

Sources

Google: Site moves with URL changes

Build in Public With a Demo People Can Reset and Test

Uriel Bitton — Thu, 15 Oct 2026 22:31:49 +0000

A public SaaS demo should start in a known state, give visitors one task to try, and let them return to the same starting point. That makes the feedback easier to interpret. If every visitor inherits a different workspace, you won't know whether they struggled with your change or somebody else's leftovers.

When you build in public, the demo is part of the conversation. A screenshot can explain what changed. A repeatable demo lets another person examine the behavior behind that explanation. It doesn't prove demand, but it can make a technical discussion much more concrete.

Define one task before preparing the workspace

Use a task with a visible finish. For a fictional invoice-review tool, the task might be: import the supplied sample file, find the row that needs attention, correct it, and review the final total. This is a worked example, not a description of Buildside's features.

Don't ask visitors to “explore everything” and then compare their reactions as though they attempted the same work. Exploration is useful when that is the research question. It is less useful when you need to understand why a particular step fails.

Write the task in customer language. “Review this sample invoice before export” gives someone an outcome. “Click the orange button, open the second tab, and edit row four” mainly checks whether they can follow your directions.

Make the initial state inspectable

For the fictional demo, prepare one small sample file with invented businesses and amounts. State how many rows it contains, which condition needs attention, and what the completed result should mean. Keep the fixture small enough that you can check it manually.

Record the demo version and the sample's version together. A person reporting a problem should be able to tell you which release they tried. If you change the sample halfway through collecting feedback, note that change rather than combining every response into one pile.

The demo's first screen should explain what is real and what is simulated. A visitor shouldn't have to wonder whether an action sends an invoice to a customer. Keep external side effects out of the public sample path unless they are necessary, clearly explained, and deliberately authorized.

Keep each visitor's work separate

A shared editable workspace can make a demo hard to interpret. One visitor clears a row, another sees the cleared state, and a third tries to reproduce a problem against different data. Their reports describe different starting conditions.

Choose a separation model that fits the product. A private session, a disposable workspace, or a local sample state may work. Each has different implementation costs and limits. You don't need to expose those details in the invitation, but you do need to know which behavior your demo provides.

Check the boundary with two sessions before sharing the link. Change something in one, then examine the other. If changes appear in both, decide whether the demo should be read-only or whether you need to fix isolation first. Don't label a workspace private unless you have verified that claim.

Treat reset as a user task

A reset control should say what it resets. In our example, it restores the sample import and removes the edits made during that demo session. It should not affect a real account, another visitor's work, or a production dataset.

Test reset after a successful run, after an error, and after leaving the task halfway through. Then repeat the task. The second attempt should start with the documented sample and should not inherit a stale success message, an unfinished upload, or a hidden selection from the first attempt.

Also check a page reload. Decide which state should persist and describe it accurately. A reset button that changes the screen while leaving old data underneath can produce misleading feedback even when it appears to work.

Separate a conversation from an observed test

A visitor saying “this seems easy” is giving you an opinion. Watching them finish the task without help gives you a different kind of evidence. Neither should be silently substituted for the other.

Nielsen Norman Group distinguishes interviews, which collect reported experiences, from usability tests, which observe interaction with a design. Apply that distinction to public demo feedback. A comment thread can help you find a question to investigate; it isn't automatically an observed usability session.

If you arrange a test, explain the task and observe where the person hesitates. Ask what they expected after the attempt. Don't coach them through every uncertain step and then record the result as independent completion.

Give bug reports a small useful structure

Ask for the starting state, task attempted, steps taken, expected result, and actual result. Include the demo version and relevant browser information when those details could affect behavior. Make screenshots optional and tell people to omit private data.

GitHub's issue-template documentation explains how templates and forms can encourage structured reports. You can apply the same idea to a simple feedback form. Don't require a public repository account from a nontechnical visitor unless that is appropriate for the audience.

A useful fictional report would say: “On demo version B, I imported sample A, edited the flagged row, and the total still showed the old value after I saved.” That gives you a sequence to replay. “The importer is broken” leaves the starting conditions unclear.

Publish a short demo contract

Before sharing the link, write a few plain sentences covering the starting sample, the task, the finish, the reset behavior, and known limits. Think of this as a promise about the demonstration, not about your entire product.

For example: “This demo uses fictional invoice data. Try correcting the flagged row and checking the review total. Reset restores the original sample for your session. Export is simulated and no messages are sent. This version doesn't support your own files.”

That contract is a proposed format for clearer feedback. It isn't a claim that this exact design has been tested. Adapt it to the behavior you have verified. If a limitation changes what someone can learn, put it beside the invitation rather than hiding it at the end of a long release note.

Link public progress to a testable change

A build-in-public update can now point to something concrete: which behavior changed, why you changed it, which task someone can try, and what feedback would affect your next decision. Keep the request focused on that change.

On Buildside, founders share progress, questions, and lessons. I founded Buildside. It can provide context around a demo and its next iteration; the demo still needs its own reliable starting state. Don't assume that everyone who follows a founder is a likely customer or has time to run a full test.

Link the relevant update to a stable explanation of the demo. If you replace the demo version later, preserve enough context that an older comment still makes sense. Otherwise a good report can look impossible simply because the product changed underneath it.

Review the results before changing the product

Keep task observations apart from feature suggestions and general praise. A reproducible error may deserve an immediate fix. A suggestion for a different workflow needs more context about who needs it and why.

Record failed attempts as well as successful ones. If a visitor stopped because the sample was confusing, don't quietly label that a product failure. Repair the demonstration and run the task again. If the sample is clear and the same behavior still causes trouble, investigate the product path.

You can report a small result honestly: which version was tried, which task was attempted, what happened, and what you changed next. Avoid publishing a success percentage from a handful of informal attempts as though it describes your whole audience.

Before your next public demo, repeat the full path yourself twice and check it from a second session. Make the task, starting state, and reset behavior easy to understand. That gives the people helping you a fair chance to produce feedback you can use.

Hey I'm Uriel Bitton. I write about building in public strategies and growing startups.

Subscribe for more stories on growing your audience by building in public.

Join us on Buildside: the social network for founders building in public.