Even without that particular misunderstanding I found it very hard to initially parse what this was actually about; I'm skeptical that a naïve non-technical person will be able to work out what it's banging on about. Maybe they're expected to arrive from some other origin with a bit more context?
To me "Docs like code" conjures up documentation that looks like code, so I think something like "The basics of using programmers' tools to create documentation" would be clearer.
Thanks for pointing this out. The post starts from the assumption that people have at least heard of "docs like code", because it's a widely-used term/practice in tech writing. So I was aiming at tech writers who heard the term, but lacked the knowledge to use the technique (original draft of the post was in response to a less technical tech writer asking me a ton of questions)
But perhaps I need to explain this up top, rather than hoping people will hang in there until the explanatory section.
Not "like": As -- meaning, "create docs as you create code", meaning "using the same tools and methods."
There is a good strong evidence that your version is inferior: the dozens of comments in this thread by people baffled by the phrase, or pointing out its flawed construction.
It's the Docs As Code approach, _NOT_ "docs like code".
Approaches to creating documentation
Docs as Code
Docs as Code at Write the Docs
Docs as Code at other conferences, video casts and articles
DocOps
What is DocOps, anyway?
Who practices DocOps?
DocOps resources
This really depends on where you first encountered the term. Anne Gentle wrote Docs Like Code, the first book I read on this topic 8 years ago. I always consider the terms "docs as code" and "docs like code" to be interchangeable, and usually use both when discussing the topic with an audience that includes a wide variety of different individuals. I think "docs as code" is probably used more in purely dev circles due to the proliferation of the "everything-as-code" construction seen in other dev-adjacent disciplines (infra-as-code, config-as-code, etc.)
FWIW, I was first taught this approach at Red Hat in 2014. I think DaC has precedence and I've never, ever encountered DlC in my work in half a dozen companies in 4 or 5 countries.
I am not saying you're wrong. I'm merely reporting my own experience.
The source is the English language, do you speak it? :)
Nouns that appear as modifiers in a compound noun are singular, and the need for a singular is so strong that English speakers invent singulars forms of plurale tantum words such as "jean jacket" rather than "jeans jacket".
There are certain cases in which a plural modifier cannot be avoided, mainly because a plurale tantum doesn't singularize. We cannot singularize "goods" in "goods distribution network"; if we drop the "s", we get an adjective which completely changes the meaning.
However, consider the word "supplies" which normally doesn't go to the singular word "supply" denoting one item. Yet in business we have "supply chain", not "supplies chain".
There is a strong urge to eliminate plurals from the non-head position of a compound noun; the urge only loses in cases when a special kind of plural cannot be eliminated.
"Docs" is short for "documents". It is widely understood to also stand for "documentation", but AFAIK even in that use, grammatically it still behaves as if it stood for "documents".
Even docs is understood as a plurale tantum noun like scissors, it still cannot be in a non-head position in a noun phrase.
If we make a noun phrase in which scissors is embedded as a non-head position, we take out the s.
We want to hear "scissor sharpening service", rather than "scissors sharpening service".
The latter is not considered grammatically incorrect, but it lacks euphony.
In some cases plural-sounding words can't be avoided in the middle of noun phrases, like "denotational semantics lecture". Semantics is a singular that people treat as a plural sometimes ("these semantics are ..."). We can't delete the "s" to make semantic, because then we get an adjective. That can be in the middle of the noun phrase, but it changes the semantics. A semantic lecture isn't one about semantics but one that has semantics (about any topic whatsoever).
I'm not sure what argument you're trying to make there; but you no longer have a four-word noun phrase here. It reads like [S law schools] [V enter] [O test].
Yes: the first position isn't special; the last is. The head of a compound noun in English is the last word. The thing denoted by A B C D is a D, first and foremost. The nouns A B C are modifiers applied to D, in the order C B A. They normally cannot be plurals.
Even when a plurate tantum such as "scissors" is used as a modifier in the non-head position, English speakers invent a singular form for it, giving rise to usage like "scissor blade".
The 1990 movie starring Johnny Depp could not have been called Edward Scissorshands.
(I would go as far as to suggest that "scissors blade", though widely used also, is a hypercorrection based on the forced idea that there is no "scissor".)
SML pops up now and again on HN, which is always nice to see. I wrote a language server for SML in an attempt to improve the tooling situation around the language: https://azdavis.net/posts/millet/
The main motivator for why I did this is because we use SML as a teaching language at my university and students always seem to struggle with the error messages and tooling from the compiler.
I think pure functions, sum/product types, and pattern matching are generally accepted as an excellent way to model and manipulate pure data. I wonder what the team’s thoughts are about handling less pure things like asynchrony and I/O, as well as more interesting control flow like exceptions/panicking, coroutines, generators, iterators, etc.
