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.
-
-
Prikaži ovu nit
-
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.
Prikaži ovu nit -
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.
Prikaži ovu nit -
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.
Prikaži ovu nit -
-
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.
Prikaži ovu nit -
Those two situations now need to evolve their usage of that fragment at the same pace and in the same direction. Otherwise you get ... CONDITIONALS.pic.twitter.com/ak0PxfX9rf
Prikaži ovu nit -
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.
Prikaži ovu nit -
Any existing conditional will attract more conditionals, because humans are nothing if not pattern followers. And when you come into the file, it sure looks like the thing to do is reuse the fragment but add your exception/special handling to the list!
Prikaži ovu nit -
I'm sure there's a law already out there about conditionals attracting more conditionals. If not, it's now Mei's First Law
Prikaži ovu nit -
In a codebase that evolves over time, the trick to keeping it nimble is to constantly be re-evaluating, for every piece of the code you look at, whether the see-saw of reuse<--->duplication is leaning at exactly the right angle.
Prikaži ovu nit -
Turns out it's the same in a big doc set. And every now and then, it turns out, the folks who own these large doc sets need to re-evaluate what they call their "reuse strategy."
Prikaži ovu nit -
Otherwise, you end up with a big ball of mud for a docset, so fragile that you can't even really tell what the consequences of even a small change will be. This drastically reduces the speed with which _any_ docs can be produced.
Prikaži ovu nit -
I'M SURE NOBODY HERE HAS ANY EXPERIENCE WITH A CODEBASE LIKE THAT NOpic.twitter.com/VtE5CUGICi
Prikaži ovu nit -
My apologies to the professional writers reading this - a) this is like super 101-level and b) I am probably using mostly incorrect terms for things. I'm just excited about the similarities I discovered today :D
Prikaži ovu nit -
In summary (because I must log off and go hound my kids to do homework and take showers), writing at scale runs into EXACTLY the same issues that software development at scale does. The concepts are represented by prose, instead of code, but the rest is the same.pic.twitter.com/3URl3UqQTc
Prikaži ovu nit
Kraj razgovora
Novi razgovor -
Čini se da učitavanje traje već neko vrijeme.
Twitter je možda preopterećen ili ima kratkotrajnih poteškoća u radu. Pokušajte ponovno ili potražite dodatne informacije u odjeljku Status Twittera.
Twitter at the speed of parenting