01 / IN-DEPTH GUIDE
Describe the exchange in plain language
An integration moves information or actions between systems. Begin by describing the exchange without naming a library or protocol. Identify the source, the destination, the trigger, the information being transferred, and the result that should follow. This description gives technical and nontechnical participants a shared view of the task. It also exposes whether the proposed connection solves a real workflow problem or merely connects tools because a connection is possible.
Specify which system owns each important fact. If both systems can edit the same field, determine how conflicting updates should be handled. If one system is the source of truth, make that responsibility explicit. A technically successful transfer can still produce an unreliable workflow when ownership is ambiguous. People need to know where a correction belongs and which copy should be trusted when the records differ. Resolve that question before automating the exchange.
Check whether an integration interface is actually available and appropriate. A product's public identity does not establish that it offers an API, an event stream, or a supported export. Look for confirmed documentation and access conditions. A workflow may instead need a file exchange or a deliberate manual step. Choose an approach based on the supported interface and the task's requirements, rather than treating a guessed endpoint or an observed internal request as an official integration contract.
02 / IN-DEPTH GUIDE
Define the contract between systems
A data contract describes what information is exchanged and how it should be interpreted. Include field names, types, required values, identifiers, units, time zones, and the meaning of missing data. These details prevent apparently valid records from carrying inconsistent assumptions. For example, an empty field might mean unknown, intentionally blank, or not applicable. The receiving system should not need to guess which meaning the source intended.
Define the timing and delivery expectations. Does the destination need the information immediately, on a schedule, or only when a person requests it? How will the system identify a duplicate event or a repeated request? What happens if the source changes a record after it has been transferred? The right answer depends on the workflow. Clear expectations allow the implementation to handle ordinary delays and repeated delivery without treating them as exceptional surprises.
Permissions are part of the contract. Determine who authorizes the connection, which records it may access, and which operations it may perform. Use the access needed for the task and avoid granting unrelated authority for convenience. Keep credentials outside client-facing code and shared examples. If an integration operates without a person present, identify how its access is maintained and how an owner can revoke it. The connection should remain understandable throughout its life.
03 / IN-DEPTH GUIDE
Design for interruptions and maintenance
Assume that a dependency can become unavailable, a request can fail, and a record can be incomplete. Define how failures are detected, which actions can be retried, and which need human review. A retry is appropriate only when repeating the operation has an understood effect. A repeated read is different from repeating an action that creates a record or sends a message. The implementation needs enough information to avoid turning recovery into duplication.
Make failures observable without exposing unnecessary data. Record the operation, relevant identifiers, status, and a useful error description. Avoid placing secrets or excessive personal information in logs. Give the owner a way to distinguish a temporary interruption from a configuration problem or a rejected request. A connection that fails silently can leave two systems looking consistent while important work has stopped moving between them.
Plan for change. Document the supported interface version, the expected schema, and the owner of the integration. Include a small set of representative checks that can be run when the source or destination changes. Define an exit path for disabling the connection without losing the authoritative records. Maintenance is not a separate concern added after launch; it is part of what makes the integration reliable enough for ordinary use.
A small design record
Before implementation, write the source and destination, the trigger, the contract, the access scope, the failure behavior, and the acceptance checks. Keep the record concise and update it when a decision changes. This gives the eventual code a clear purpose and gives future maintainers a way to understand the choices without reconstructing them from requests and log files.
04 / IN-DEPTH GUIDE
Confirm the interface and its scope
An API is an interface with an expected contract. Before writing a request, confirm that the documentation describes an official interface available for your intended use. Identify the relevant version, environment, account conditions, and access requirements. A product may expose an internal request in its own application without offering that request as a supported public contract. Building on an undocumented observation can create a fragile connection whose behavior changes without the guarantees you expected.
Read the purpose of the operation before its example. Determine whether it retrieves information, creates a resource, updates state, or triggers a consequential action. The operation's meaning matters more than the convenience of a copied command. A request that appears similar to another request may have different side effects. Make sure the action corresponds to the workflow you intend and that the current task authorizes it.
Separate examples from configuration. A sample address, identifier, or credential may be illustrative. Look for the instructions that explain what must be replaced and where the real values come from. Do not invent an endpoint when documentation is absent, and do not assume that a product name implies a package name or SDK installation command. Confirming the interface is part of the integration work, not a preliminary detail that can be skipped.
05 / IN-DEPTH GUIDE
Inspect inputs, outputs, and limits
For each request, identify required inputs, optional inputs, accepted types, valid ranges, and the meaning of omitted values. Pay attention to identifiers and time fields. A displayed name may not be a stable identifier, and a timestamp may require a specific time zone or format. Validate the shape of the request before sending it. Clear input handling makes failures easier to interpret and reduces the chance that an operation is applied to the wrong resource.
Read the response contract as carefully as the request. Identify where the result appears, whether the operation is complete or still pending, and which fields are optional. A successful transport status does not always mean that every intended action succeeded. Some interfaces report partial results or an asynchronous operation that must be checked later. The receiving code should follow the documented state rather than assume that the first response establishes the final outcome.
Look for pagination, rate limits, quotas, and ordering guarantees. A list response may contain only the first page. Records may change between requests. A limit may apply per account, token, operation, or time window. These details affect both correctness and efficiency. Avoid treating a small successful example as proof that the same approach will work for the full dataset. Test the behavior that the documentation describes and keep the assumptions visible in the integration design.
06 / IN-DEPTH GUIDE
Understand errors and repetition
Error information should help distinguish invalid input, missing access, an unavailable dependency, and a resource that does not exist. Use that distinction to decide what happens next. Retrying an invalid request without changing it will not solve the problem. Requesting broader access may be inappropriate when the task itself does not require it. A useful error strategy addresses the reason for failure rather than treating every non-success response as a temporary interruption.
Understand the effect of repeating an operation. Some interfaces provide a mechanism that lets the client recognize a repeated request and avoid creating a duplicate result. Other operations need the client to track what has already been completed. Do not assume that a timed-out response means the action never happened. The server may have completed the work before the connection was interrupted. Recovery needs a way to inspect or reconcile the actual state.
Use a controlled environment or a low-impact representative case where available. Verify both the response and the destination state. Remove secrets from shared examples and avoid logging complete authorization headers. Record the documented version and any assumptions the implementation relies on. When the interface changes, those notes make it easier to identify which behavior needs retesting instead of treating the whole integration as an unexplained failure.
A reference reading order
Read availability and authorization first, then the operation's purpose, request schema, response states, limits, errors, and repetition behavior. Finally inspect the example. This order makes the example easier to interpret and prevents it from becoming a substitute for the contract. If a necessary part is missing, keep the integration question open until reliable information is supplied.
07 / IN-DEPTH GUIDE
Start with the user's understanding
An interface is a conversation about state. It tells someone what information is available, what action can be taken, and what changed after the action. Begin by identifying the decisions the user needs to make at each step. Present the information required for those decisions before the control that depends on it. A visually impressive screen can still be difficult to use if the person has to infer the state from decoration or remember details from another page.
Use labels that describe the action or destination. A link should make clear where it leads, while a button should describe the action it performs. Avoid using the same generic label for several different behaviors. When a control changes meaning based on the current state, make that change understandable. For example, a saved draft, an approved result, and a published page should not be represented by an identical status that hides the distinction.
Group related information through spacing and alignment. Place a field's explanation and error near the field. Keep a section heading close to the paragraphs it introduces. Align repeated controls so their purpose can be compared without unnecessary visual effort. These decisions reduce the amount of interpretation the user must perform. Consistent layout is useful because it makes relationships predictable, not merely because it makes the screen appear orderly.
08 / IN-DEPTH GUIDE
Build the states, not only the ideal screen
Every meaningful flow has more than its successful state. Identify what appears before data arrives, when the collection is empty, while an action is in progress, and when the action fails. Write the message for each state in plain language. A useful empty state tells someone whether there are no records, whether a filter excluded the records, or whether the data could not be loaded. Those situations require different explanations and different next steps.
Loading should preserve orientation. Keep the relevant heading, labels, and surrounding structure visible where possible. Reserve space for content to reduce disruptive shifts. If an operation takes time, communicate progress without inventing precision the system cannot support. A busy indicator should not imply that the work is nearly complete when the application only knows that the request is still pending. Honest state descriptions help the user decide whether to wait or take another action.
Errors should explain the observed problem and the available response. Avoid a generic failure message when a more specific explanation can be provided safely. Preserve input that can be retained without creating another problem. Make field errors readable and associated with the relevant controls. If the user can retry, explain whether retrying repeats the whole action or only the failed part. Recovery is part of the interaction contract, not an afterthought attached to an exception.
09 / IN-DEPTH GUIDE
Preserve clarity across input methods
Use native links, buttons, labels, and form controls when they match the behavior. These elements provide familiar interaction and useful accessibility semantics. Custom visuals can be layered onto them without replacing their meaning. A clickable container should not masquerade as several different controls unless the design makes the separate actions clear. Keyboard users need a predictable order and a visible focus indicator, just as pointer users need an understandable target.
Check menus and overlays as complete interactions. Opening is only one part of the behavior. A modal flow also needs appropriate focus, a way to close, a return destination for focus, and a sensible response to viewport changes. A disclosure should expose whether it is expanded and remain operable without hover. Test the actual sequence with the keyboard. A screenshot of the open panel does not establish that a person can enter, use, and leave it reliably.
Make the content resilient. Test long names, larger text, translated labels where relevant, empty records, and narrow screens. Allow meaningful content to wrap rather than forcing a single line that breaks the layout. Keep intentional scrolling inside the component that needs it, such as a wide table, instead of hiding page overflow. The interface should remain understandable when ordinary content differs from the carefully chosen example used during design.
Review one complete task
Choose a representative task and walk through its initial, working, successful, empty, and failed states. Check the same task with keyboard input and at a narrow width. Write defects as specific observed behaviors and expected outcomes. This creates a practical path from design intent to reliable interaction and gives the next repair a clear acceptance check.
10 / IN-DEPTH GUIDE
Choose checks that answer real questions
A test should verify behavior that matters to the task. Begin with the main visitor journey and identify the points where a failure would interrupt it. For a content site, those points may include navigation, search, direct child-page requests, readable layouts, and a working contact state. For a working application, they may include input validation, saved state, permissions, and recovery. Let the product's purpose determine the checks rather than adding tests merely because a framework makes them easy to write.
Use different kinds of evidence for different claims. A type check can catch certain code inconsistencies. A production build can show that the application compiles. A route request can show that a page resolves. A browser interaction can show that a control behaves correctly. A screenshot can reveal wrapping and alignment. None of these establishes every other property. A strong review combines the evidence needed for the conclusion and states the limits of what was actually checked.
Prioritize the consequences of failure. A broken primary action, inaccessible navigation, or misleading success message deserves attention before a minor decorative inconsistency. This does not mean visual quality is unimportant. It means the review should distinguish a defect that blocks the visitor from a refinement that improves an already usable experience. A short prioritized list makes repair work more efficient and avoids spending the entire review on whichever issue is easiest to notice.
11 / IN-DEPTH GUIDE
Combine automated and manual review
Automated accessibility tools can identify useful problems, including some missing names, invalid relationships, and contrast issues. They cannot establish complete accessibility on their own. Manual checks are needed for reading order, meaningful labels, keyboard behavior, focus visibility, and the practical clarity of a flow. Where assistive-technology testing is available, include it in the relevant journeys. If it is unavailable, report that limitation instead of implying coverage from a different kind of test.
Inspect responsive behavior with real content. Test a narrow screen, a typical mobile width, an intermediate layout, and a desktop composition. Include long headings and paragraphs, not only the shortest examples. Enlarge text and observe whether the content remains usable without clipping or page-wide horizontal scrolling. A layout can pass a few fixed screenshots and still fail when a user changes text size. Responsive quality includes that adaptation.
Test state changes deliberately. Open and close menus, clear search, apply a filter that returns no results, enter invalid data, and interrupt an operation where the environment permits a controlled check. Confirm that the interface describes each result accurately. For a preview form without a delivery service, the important test is that it cannot imply a successful message transmission. The acceptance check should match the actual implementation rather than a feature that has not been configured.
12 / IN-DEPTH GUIDE
Keep a repair loop with evidence
Record a defect with the page, viewport or state, observed behavior, expected result, and a proposed repair. Capture evidence when it helps explain the issue. After changing the relevant component, rerun the affected check and inspect related shared behavior. A repair to a global heading style may need more than one page review because it can change several compositions. A narrow content correction usually needs a narrower verification.
Do not repeat every check indefinitely after an unrelated change. Reuse successful evidence while its inputs remain unchanged, and expand the review when a new failure or concern justifies it. If two attempts on the same issue make no progress, investigate the underlying cause. Repeating the same action with no new information consumes time without improving confidence. A useful test process learns from failures and changes approach when the evidence requires it.
Prepare the handoff so another person can reproduce the result. Record the actual commands, tested routes and states, and any blocked checks. When source is packaged, include the files needed for a clean installation and build. Exclude local dependencies, caches, secrets, and unnecessary scratch material. A clean archive test can reveal missing configuration that the working directory silently supplies. Reproducibility turns a one-session result into a usable project.
Report precisely
Say that the tested routes, viewports, and interaction states passed, and identify the tools or limitations relevant to that statement. Do not claim universal compliance or perfect behavior from a finite review. Precise reporting is more useful than a broad assurance because it tells the next person what they can rely on and where additional evidence may be needed.
13 / IN-DEPTH GUIDE
Relevant evidence matters more than volume
A system can receive a large amount of text and still lack the fact needed to answer a question. Start by identifying the information required for the task. Which records establish the current state? Which documents explain the rules? Which source resolves a disputed detail? Gather those sources deliberately rather than attaching everything available. A smaller collection of relevant, current evidence is often easier to use and review than a large collection containing unrelated or contradictory material.
Different sources have different roles. An approved policy establishes a rule. A transaction record establishes an event. A working note may contain an interpretation. A public article may provide general context. Keep those roles visible when preparing material. The system should not treat an informal suggestion as an approved requirement or a historical example as the current state. A useful answer depends on both the content of a source and its authority for the question being asked.
Freshness is especially important for changing facts. Availability, prices, account permissions, and operational status can become outdated. Record when a source was last updated and whether it applies to the current situation. Do not automatically prefer the newest document if it is less authoritative or addresses a different scope. When sources disagree, identify the conflict and seek the rule for resolving it. Concealing the conflict inside a confident answer makes later verification harder.
14 / IN-DEPTH GUIDE
Understand what retrieval does
Retrieval selects information from a larger collection for a particular question. It can help a system use documents or records that are not contained in its training. Selection may depend on keywords, semantic similarity, filters, permissions, or other mechanisms. A retrieved passage is a candidate source, not a guarantee that it is complete or correct. The surrounding application still needs to decide whether the passage answers the question and whether important context has been omitted.
Document structure affects retrieval quality. Clear titles, meaningful headings, stable identifiers, and well-organized paragraphs make information easier to locate. A long page that mixes unrelated subjects can make selection less precise. However, splitting content too aggressively can remove the context needed to interpret a passage. The goal is coherent units of information that remain connected to their source and neighboring sections. Good document organization helps both people and retrieval systems.
Permissions need to travel with the information. A system should only retrieve material that the current task and user are authorized to access. Do not assume that all documents in a shared collection can be used for every purpose. When a result includes restricted or personal information, consider who will receive the answer and whether the content is appropriate for that destination. Retrieval is an access and context problem as well as a search problem.
15 / IN-DEPTH GUIDE
Keep the answer connected to its sources
Attribution helps a reader inspect a claim. A useful source reference points to the material that actually supports the statement, not merely to a vaguely related document. Where possible, retain a stable link, title, or record identifier. Explain when the answer combines several sources or adds a general inference. This allows the reader to distinguish direct evidence from interpretation and to check the part of the answer that matters most to the decision.
Handle missing evidence explicitly. If the collection does not contain a current answer, the system should say what is missing rather than filling the gap with a plausible detail. An answer can still be helpful by narrowing the question, listing the known facts, or identifying the source needed next. Do not treat a no-results state as a failure that must be disguised. An honest limitation preserves the difference between available evidence and unsupported assumption.
Test retrieval with representative questions. Include a straightforward lookup, a question requiring several related facts, a question with an ambiguous term, and a question whose answer is absent. Inspect the selected passages as well as the final response. If the wrong material is selected, improving the wording of the generated answer may not solve the underlying problem. The repair may involve source structure, filters, indexing, or the way the task identifies relevant context.
A source preparation habit
Before an important AI-assisted task, identify the authoritative sources, note their scope and freshness, remove irrelevant material, and preserve references. Afterward, check whether the answer used those sources appropriately. This small discipline makes both generation and review easier. It also provides a clear explanation when the system cannot answer because the necessary evidence is unavailable.
For confirmed company and product information, visit Developers. Explore the rest of the reading room for more general guidance.