Composability (noun)

The ability to combine independent parts, unchanged, into new arrangements for different purposes.

About Composability

Suppose our organization publishes product documentation to an online documentation portal and to help panels inside some of our products, and plans to add an AI assistant as a third channel.

The account-creation procedure belongs in the portal’s getting-started section, in the help panel on the sign-up screen, and in any answer the AI assistant gives about getting started. If we write each piece as a self-contained topic, our publishing system can arrange the topics one way for the portal and another for the help panels, and the AI assistant can retrieve the topics relevant to a question.

That arrangement works only when each topic makes sense on its own. A procedure that begins “Now that you’ve completed the steps above” depends on the page it was written for. Publish it in another channel, and the steps it refers to aren’t there, so someone has to edit it first.

Why Tech Writers Need To Understand Composability

Read more

Enabling capability (noun)

An ability that makes another capability or a desired outcome possible, or supports its effective delivery.

About Enabling Capabilities

Suppose our organization plans to introduce an AI assistant to help customers complete routine tasks using our product documentation as the source content. The assistant needs a retrieval system that finds and returns instructions that match each customer’s situation. This capability helps the assistant give trustworthy and useful answers.

Finding the right procedure is an important part of delivering effective self-service user assistance. The procedures we deliver to our users must be correct, and the assistant must be capable of explaining it clearly and providing an answer that addresses their individual needs. If our customer doesn’t have permission to complete the task they seek to perform, our AI may need help from an administrator.

A capability is an ability an organization or system has. TM Forum’s business capability guidance explains how people, processes, information, and systems contribute to that ability. When one capability helps make another possible, it serves an enabling role.

Why Tech Writers Need To Understand Enabling Capabilities

Read more

Verifiability (noun)

The extent to which a claim can be checked against evidence to determine whether it is correct under the stated conditions.

About Verifiability

Suppose our product guide says: “Administrators can restore deleted projects within 30 days.”

Our customer asks whether the policy applies to projects deleted from their trial account. Our writer finds the same restoration info in several places, but none of them tells them which account types our policy covers; nor does it tell them why the limit is 30 days.

Before confirming the information, our writer needs evidence specifically about restoring projects from trial accounts. That evidence might come from our product specifications, test results, or the product subject matter expert responsible for the feature.

Verifiability means checking whether a claim is true. A statement can be correct, and at the same time, hard to verify (if no supporting evidence is available).

Why Tech Writers Need to Understand Verifiability

Read more

Retrievability (noun)

An enabling capability that determines whether a retrieval system can locate and return the right content for a given query.

Suppose our docs include the correct procedure, but the way we present the additional information needed obscures the right answer.

Perhaps the heading we chose reads “Exporting data” and the name of the product sits near the top of a long page of procedural info. And, the cloud-only restriction lives in a note.

If an AI retrieval system searches thru short passages from our docs, it may retrieve the procedure without the detail that says it applies to the cloud version. Or, perhaps it accesses the step-by-step instructions without finding the note that qualifies it. As a result, a similarly worded procedure for on-premises users may be referenced to generate an answer instead.

Even when the correct answer appears in our docs, unclear wording or poor content organization choices can make it harder for a retrieval system to differentiate it from other similar procedures.

Writers shape how documentation reads and how it’s organized, including the metadata attached to it. The retrieval system determines what gets indexed and how a query is matched against it.

Why Tech Writers Must Understand Retrievability

Clear writing alone can’t resolve the kind of gap the audit-log example shows. If retrieval never surfaces the right passage, no amount of good writing fixes what the model never saw.

We tech writers make all sort of choices a retrieval system can find. In the audit-log example, using the heading “Exporting data” is one of those choices. A specific task name gives the system more context when it looks at that passage by itself.

The same is true of consistent terminology that distinguishes similar features and applicability statements that clearly identify a cloud-only restriction, rather than relegating it to a separate note elsewhere in the docs.

Understanding retrievability helps us see that the answer can be in our docs but still fail to appear when someone needs it. Finding out why it fails may require us to work with customer support teams or the others who manage search and AI systems.

We bring our knowledge of the documentation: which procedure answers the question and the conditions under which it applies. When we can see real user questions and the system’s results, we can use that knowledge to investigate specific failures.

What Retrievability Looks Like In Documentation

Read more

Query constraint (noun)

A condition that limits which information can qualify as a valid result for a query.

About Query Constraints

When someone asks a question of our documentation, the subject is only part of what a retrieval system needs to understand.

The subject is exporting audit logs. But the question also contains two conditions: the answer has to apply to administrators, and it has to apply to the cloud product.

A procedure written for on-premises customers (not using the cloud version) can use nearly identical language and still be the wrong answer for those folks. So can a procedure written for end users instead of administrators. Both can look highly relevant to a search system while failing to satisfy what the question askers actually require.

Those conditions — role, deployment, and dozens of others like them — are query constraints. Oracle describes search constraints as a way to limit the search space within an index. Firebase defines a constraint as something used to narrow the set of documents a query returns.

The concept isn’t new. What’s changed is what happens when the wrong constraint slips through undetected.

Read more

Deterministic system (noun)

A system whose rules produce the same output whenever it receives the same inputs under the same operating conditions.

About Deterministic Systems

Deterministic systems follow rules that determine what happens. Start with the same state, feed in the same inputs, and the system applies the same rules, resulting in the same result every time.

A calculator is the simplest example.

Enter 10 × 5 and you get 50, every time.

Software permissions work the same way. If access depends on a user's role, subscription level, and security settings, the system reaches the same decision whenever those values match.

Same inputs covers more than what our users type in. It includes things like account settings, stored data, software version, current time, feature flags, and information pulled from connected services. Change any one of those inputs, and our result can change too.

What Makes A System Deterministic?

Subscribe now

Read more

Inference gap (noun)

A fact, condition, relationship, exception, or consequence that an audience needs but the content doesn’t explicitly state.

What Creates Inference Gaps?

Tech docs can be 100% accurate and still leave readers (and machines that access our content) completely in the dark. Sometimes an important fact is missing. More often, however, the writer understands exactly how the system works but fails to put those connections in our docs.

They leave out unwritten rules, like:

• who a policy applies to

• when it kicks in

• what the exceptions are, or

• how flipping one switch changes something else

When these connections in our content are missing, readers (human or otherwise) are forced to fill-in-the-blanks by guessing. A human might rely on trial-and-error, past experience, or interface clues. An AI tool will try to stitch scattered sentences together and invent an answer.

Guesswork is a problem when it changes how someone understands our instructions or makes them uncertain what action they should take or what happens if they get something wrong. We don’t have to explain every possible detail imaginable (that’s not a practical solution), but we need to connect-the-dots clearly enough that readers don’t have to guess to get a reliable answer.

Common causes include:

Subscribe now

Read more

Inference load (noun)

The amount of unstated information a person or machine must supply to understand content, connect related facts, or decide what to do.

About Inference Load

What Creates Inference Load?

Inference load is created when technical documentation leaves important relationships implicit. Readers and AI systems must determine how facts fit together, whether a rule applies, and what conclusion the content supports. Neither people or machines are particularly good at that.

What Inference Load Looks Like

Read more