Sarah MeiVerified account

Large companies often have huge amounts of written documentation. Salesforce, for example, has docs for end users, potential customers, employees of all stripes, external developers, and literally dozens of other categories of people.

Most of these pieces of documentation (save maybe github READMEs, and even those sometimes) are written by professional writers. But at scale, their output can't be just unstructured documents, like, just like opening a word doc and typing.

What they're writing has to be structured - broken down into component parts. This is for a number of reasons, but the one most interesting to us is _reuse_. They need to use pieces of a document in multiple places.

And why do they want to reuse elements? 1. Because the same information needs to appear in multiple places - developer docs & internal docs, for example - but when it changes, they don't want to have to hunt down all the places it's referenced and change each one, one at a time.

But just like with code, reuse is not 100% good all the time. Every time you reuse something, you are creating a dependency between the two situations where you use it.

And just like with code, in a small codebase [doc set] with only a few developers [writers] on it, a conditional here & there is fine. But when you've got hundreds of developers [writers]...it stops working quick.