5 exercises — choosing the right connectors (although, whereas, however, consequently, therefore) in design docs, ADRs, PR descriptions, and runbooks.
0 / 5 completed
1 / 5
A technical writer drafts: "The new architecture reduces latency. _____, it increases memory usage." Which discourse marker best signals a contrast?
However is the standard adversative discourse marker for contrasting two clauses in technical documentation — design docs, ADRs, and PR descriptions regularly use it to present trade-offs: "The migration reduces costs. However, it introduces operational complexity."Nevertheless concedes a point and pushes back against it ("Despite problem X, we should proceed") — slightly stronger than "however" and used after a negative premise. Furthermore is additive, not contrastive. Therefore is causal. In ADRs, "however" signals the problem with a chosen approach; "nevertheless" signals why the team chose it anyway.
2 / 5
An ADR reads: "REST was considered. _____ the team preferred gRPC, the service layer already uses REST extensively." Which word fits the blank?
Although is a subordinating conjunction that introduces a concessive clause — it connects two contrasting facts within a single sentence. "Although the team preferred gRPC, the service layer already uses REST extensively" signals that the preference was overridden by a practical constraint. This structure is extremely common in ADRs to explain why a seemingly better option was not chosen. "In addition" is additive. "As a result" is causal (consequence). "For instance" introduces an example. Note: "although" introduces a subordinate clause; "however" would need a new sentence or at least a semicolon.
3 / 5
A PR description states: "The old approach mutated shared state. The new approach uses immutable data structures. _____, concurrency bugs are eliminated." Which marker correctly signals the result?
Consequently is a causal discourse marker meaning "as a result of what was just stated." In this sentence, immutable data structures logically cause the elimination of concurrency bugs — "consequently" makes that causal chain explicit. In contrast and whereas signal comparison or contrast, not causation. Despite this concedes the previous point and introduces a surprising counter-result. In technical writing, causal chains are common: "The index was dropped. Consequently, query time increased by 300ms." Use "consequently" in post-mortems, performance analyses, and root cause sections.
4 / 5
A design doc compares two databases: "PostgreSQL offers ACID guarantees. _____, Redis prioritises low latency over durability." Which marker is most appropriate?
Whereas is a contrastive subordinating conjunction used to compare two different things, people, or situations in a single sentence. It is the preferred marker in technical writing for side-by-side comparisons: "PostgreSQL guarantees durability, whereas Redis favours availability and speed." "Whereas" is more compact than "on the other hand" and fits naturally in comparative analysis sections of design docs. Similarly signals similarity, not contrast. Moreover adds information. Hence signals a conclusion or consequence. In database comparison tables and trade-off sections, "whereas" is the go-to contrastive connector.
5 / 5
A runbook states: "The service may fail to start if the config file is missing. _____, always verify the config path before deployment." Which marker signals logical advice following a warning?
Therefore introduces a logical conclusion or recommendation based on the preceding information. In runbooks and operational docs, the pattern is: [observation or risk] + Therefore + [action or recommendation]. "The config file may be missing. Therefore, always verify the path." This is the standard causal-advisory structure in technical writing. Nevertheless would imply proceeding despite the risk (opposite meaning). In contrast signals comparison. Although introduces a concession. Use "therefore" when the second sentence is a direct logical consequence of the first — particularly in runbooks, incident playbooks, and deployment guides.