SYSE.26 - Design a Supported Platform-Use Path
Normativity: Guidance within the stated engineering use; examples are illustrative.
SYSE.26:1 - Problem frame
Use this pattern when a practitioner knows the engineering result needed next but must repeatedly discover how to request it, which inputs are acceptable, what a delay or failure means, or how to recover. A developer asks for a test environment, a test engineer asks for a bench run, or a manufacturing engineer asks for an inspection result. The available tools may work while the interaction between their users and providers remains unreliable.
Start with one representative attempt and say what the user supplies, what usable result should return, and which conditions make the attempt supported. Design that interaction through success, variation, waiting and failure. The first useful result is a usable supported-use description, with a trial or a precise missing provision identified. It is not evidence that the described platform already works.
Platform Engineering concerns Systems that enable their users’ work. This pattern concerns one way of obtaining a result through those Systems and their providers, not every aspect of the platform. If the desired improvement is still unclear, use SYSE.25 to choose it. If complete alternative obtaining arrangements must be compared, use SYSE.24. If the interaction is already clear but the underlying professional operation is not qualified, address that operation rather than redesigning the entry form. An already sufficient one-off tool result needs no supported-path redesign. When the provider’s offered result and conditions themselves are unclear, use SYSE.8 to develop that provider concept before making the promise.
SYSE.26:2 - Problem
A user can submit a valid request yet receive only a job number, a generic error or a link to an obsolete result. A provider can report technical completion while the user still lacks the configuration, evidence or access needed for the next engineering action. Repeating the request may create a second environment or repeat a physical operation that cannot be undone.
The missing engineering work is to connect the user’s undertaking to the actual accepted inputs, operations, returned result and support. The connection must survive the cases users really encounter, not only a provider’s successful demonstration.
SYSE.26:3 - Forces
| Force | Practical tension |
|---|---|
| Simple entry | Hiding irrelevant implementation detail helps; hiding a condition that changes the result makes use unsafe. |
| Supported variation | A common route reduces repeated effort, but one rigid template can exclude legitimate work. |
| Retry and recovery | Users need a next move after uncertainty; repetition can duplicate an already completed effect. |
| Low coordination | Self-service can reduce case-specific assistance, while maintenance and exception support still need capable providers. |
SYSE.26:4 - Solution
SYSE.26:4.1 - Begin with the user’s completed undertaking
Walk through an actual or explicitly constructed attempt with a representative user. Ask what they will do with the result: compare a model, test a change, release a configuration, or accept a manufactured item. Work backwards from that use to the smallest sufficient input and returned result.
Keep the user’s result separate from intermediate provider activity. An accepted request, a booked slot, a running job and an inspected item are different results. A booking may be sufficient when the user is scheduling; it is insufficient when they are deciding whether a component passed a test.
Name the System or provider that supplies each indispensable operation. Recover existing configuration identities and conditions through SYSE.13. When a professional Method is missing, name its required result and supplier. A clear description of a missing operation is useful for design, but does not justify promising that operation to users.
SYSE.26:4.2 - Bound the supported interaction
Choose a small, coherent class of supported attempts. Determine the required input, valid variants, applicable permissions, limits, return format and conditions under which the result is usable. Expose only the choices users need to make; derive safe defaults from known facts rather than guessing omitted engineering conditions.
For each material variation, choose a supported route, a provider-assisted route, an extension request or an explicit unsupported answer. An unsupported but legitimate request is not an invalid request. Do not coerce it into a template whose result answers a different question. Use SYSE.27 when contributors need a maintained extension path.
Use an interface already natural for these users when it suffices: a callable operation, a command, a workbench interaction or a short agreed request can provide the supported interaction. A new portal is justified only by an additional user result. Pass required credentials through the applicable protected authentication mechanism. Keep credentials and personal data out of task request and response payloads, displays and diagnostics. Include only diagnostic detail needed to understand the result or take the next action.
SYSE.26:4.3 - Make progress, result and uncertainty distinguishable
Decide what the user can observe at the points that change their next action.
| Situation | What the user needs to know | Admissible next move |
|---|---|---|
| The request was not accepted | Which input or permission is missing, and whether any effect occurred. | Supply the required input or request the missing permission from the person authorized to grant it. |
| Work was accepted and is waiting or running | A retrievable attempt identity, present progress and the meaningful limit or support condition. | Observe the same attempt; cancel only under the stated cancellation semantics. |
| The operation completed | The returned result, its configuration and usable conditions, not merely the worker’s exit status. | Use the result for the named next action. |
| The operation failed or its state is unknown | Observed partial effects, remaining uncertainty and the safe recovery or support return. | Reconcile actual state before a replay that might duplicate effects. |
These are semantic distinctions, not compulsory status labels or a universal workflow. A synchronous operation may need no persistent job record. An operation with uncertain external effects needs enough stable identity and observation to recover the same attempt.
Design reattempt and cancellation around the actual effects. If a provider can look up an earlier attempt, use that lookup before creating a replacement. If it cannot establish whether the effect occurred, return the uncertainty and restrict further action. Cancellation of a request does not necessarily cancel provider work or reverse a completed effect. Domain-specific state recovery remains with its qualified Method; software/data recovery uses SYSE.34.
SYSE.26:4.4 - Keep support connected to the failed use
Make the support return available where the user encounters the failure. Carry the attempt identity, relevant input/configuration, observed result and last safe action, subject to confidentiality. The user should not have to reconstruct a hidden chain of provider job numbers.
Determine who can actually investigate or repair the provision and which promise is in force. If the assignment is missing, ask the person authorized to assign support who will provide it; a support-link label does not appoint a provider. Keep the user’s continued-work option visible, including a bounded manual route when it is usable and permitted.
SYSE.26:4.5 - Exercise the interaction before relying on it
Try the supported case with a representative user and the intended result consumer. Include one valid variation, one invalid or unsupported request, one delayed attempt and one interrupted operation whose effect may already have occurred. Check that each leaves an intelligible next move and preserves the result’s identity.
A desk walkthrough tests the description. A trial against the actual provision tests more: whether the request reaches the right System, the operation works under the stated conditions and the result can be used. Keep those evidence claims separate. SYSE.12 distinguishes a readiness assessment made before relying work from a later assessment of actual use; SYSE.36 helps observe software-service user tasks. Stop at the design result or bounded trial result that the current decision needs.
SYSE.26:5 - Archetypal Grounding
A constructed ParcelWorks example begins with: “Give me an isolated preview environment for service change r17, so I can run the address-form acceptance test.” Developers already have a CI entry and a registry; a new user interface is not assumed necessary.
The supported request identifies r17, the chosen service variant, a versioned environment recipe and synthetic test-data set s4. The response must identify the created environment, its observed configuration, access instructions and expiry condition. The underlying environment-construction Method supplies the environment; this pattern supplies the interaction by which the developer obtains and interprets it.
In the first walkthrough, the provider accepts attempt q17 and creates environment e42, but the response is lost. A second click with a new request identity would create an unnecessary second environment. The revised interaction retains q17 at the caller, permits retrieval of that attempt and returns e42 only after checking its current state. If that lookup is unavailable, the response says that creation is uncertain and returns q17 to support; it does not invite an unqualified create-again action.
A later constructed trial finds the environment running but the acceptance-test connection denied. “Created” is therefore not the promised usable result. The trial returns the observed access failure and its repair route. After the permitted access configuration is repaired and the connection checked, the developer receives e42 with the matching recipe and data identity. This is still no approval to release the application.
A request for an unsupported build language receives a specific extension/support answer. It is not silently run through another language’s recipe. Expiry is also visible: the user can retain the permitted test result before the disposable environment is removed, rather than treating access to a disappearing environment as permanent evidence.
For a physical test bench, the same design question separates a reservation from a completed measurement. A request can name component configuration C4, the intended operating range and the measurement needed for an engineering decision. The returned booking confirms only a slot. The later measurement result also needs the actual specimen, setup and applicable measurement qualification. Software-style resubmission cannot safely repeat a destructive test, so an uncertain run returns to the operator before another specimen is consumed.
The practical change in both cases is that the user can distinguish what has been obtained and what is still missing.
SYSE.26:6 - Bias-Annotation
Evidence from frequent expert users can hide the difficulties of infrequent users and unsupported variants. Include people who abandon the route or require assistance. Software examples also make replay look cheap; physical changes, consumed specimens and external commitments can make the same action irreversible.
SYSE.26:7 - Conformance Checklist
- A representative user’s next engineering result, supplied input and supported conditions are concrete.
- Acceptance, progress, intermediate completion and the usable returned result remain distinguishable.
- Valid unsupported use has an explicit return rather than a false success or coerced variant.
- Retry and cancellation preserve known effects and expose unknown ones.
- The support return reaches an actual capable provider without inventing an assignment or permission.
- Description, desk walkthrough, actual trial and later use support only their own evidence claims.
SYSE.26:8 - Common Anti-Patterns and How to Avoid Them
| Misuse | Repair |
|---|---|
| A completed backend job is reported as the user’s completed task. | Check the returned result with its intended consumer and expose any remaining condition. |
| A timeout offers “try again” without an attempt lookup or effect check. | Recover the earlier attempt and reconcile its effect before replay. |
| Every request is forced into the common template. | Distinguish invalid input from a legitimate unsupported variant and provide the corresponding return. |
| The support page lists a team that cannot repair the failure. | Recover the actual provider capability and assignment, or state that support is not yet supplied. |
SYSE.26:9 - Consequences
Users gain a smaller set of decisions and a usable next move after failure. Providers gain evidence that connects a fault to a user undertaking. Designing and maintaining variant, feedback and recovery behavior costs effort; a small stable interaction should remain small rather than acquire a universal request catalogue.
SYSE.26:10 - Rationale
An enabling System matters through the work people can complete with it. Designing only the successful technical operation leaves users to integrate configuration, interpretation and recovery themselves. Exposing the conditions that change their next action reduces that hidden integration work.
SYSE.26:11 - SoTA-Echoing
For the question “How should an internal platform let users obtain a usable result?”, adapt the task-oriented, minimum-use-path and clear-feedback line in DORA Platform engineering. It changes sections 4.1–4.3: begin with the task and expose its outcome, instead of selecting a portal or measuring submitted jobs. The trade-off is more deliberate exception design for less user-side diagnosis. DORA’s software findings do not demonstrate the physical-bench result.
Adopt the thin-interface-over-actual-providers alternative in the CNCF Platforms White Paper, where it supplies the same user result. Compared with rebuilding every provider capability, it avoids unnecessary implementation while retaining the support and compatibility burden. Compared with a bare collection of links, section 4.4 keeps an actionable failed-use return. The selected interface may still be manual; no centralization or portal preference follows.
Reopen the comparison when representative users cannot recover from a supported failure, a legitimate variant repeatedly bypasses the path, or a different interface supplies the same bounded result with less total user and provider effort.
SYSE.26:12 - Relations
SYSE.25 selects the task improvement; SYSE.24 compares whole obtaining arrangements. SYSE.12 develops the enabling System and separates readiness from later use. SYSE.13 supplies configuration identity. SYSE.27 develops contribution and compatibility paths; SYSE.28 places already justified controls. Software environment construction, state recovery and task measurement are supplied respectively by SYSE.33, SYSE.34 and SYSE.36. Actual release authority remains with SYSE.14 and the applicable holder.