5 ms·

I didn’t realize that “docs like code” was a noun phrase and was trying to figure out how docs can be liking code that is in basic terms.

kazinator 1y ago
docs is plural. You can't have a plural in a noun phrase, other than in he head position. For instance OK, no plurals: law school entrance test OK, head plural: law school entrance tests ?? non-head plural: law school entrances test
- HumanOstrich 1y ago
  Interesting. Can you provide some source(s) for this rule?
  - eru 1y ago
    Especially since people like to play fast and loose with things like plurals in set phrases. See eg https://www.youtube.com/watch?v=AxlzkJAK1BM&t=22s https://www.youtube.com/watch?v=AxlzkJAK1BM&t=22s
  - kazinator 1y ago
    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.
- simonw 1y ago
  "Docs" is short for "documentation", not "documentations".
  - PhilipRoman 1y ago
    It's kind of its own thing at this point, people write "design doc" in singular so "docs" could very well be short for "documents".
    - hunterbrooks 1y ago
      Bingo - it’s colloquially
  - TeMPOraL 1y ago
    "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".
    - kazinator 1y ago
      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).
  - kazinator 1y ago
    https://news.ycombinator.com/item?id=43928303 https://news.ycombinator.com/item?id=43928303
- jstanley 1y ago
  "law schools enter test"
  - kazinator 1y ago
    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].
    - jstanley 1y ago
      In "docs like code" the first noun is plural. Your examples were pluralising other words.
      - kazinator 1y ago
        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".)
MathMonkeyMan 1y ago
time flies like an arrow
- 3dprintscanner 1y ago
  And fruit flies like a banana
dcminter 1y ago
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.
DeborahWrites 1y ago
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.
- lproven 1y ago
  > it's a widely-used term/practice in tech writing But it's not. You have got the key phrase wrong! It's Docs as Code. There are whole websites devoted to it: https://docsascode.org/ https://docsascode.org/ 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". https://docascod.github.io/howto/#/ https://docascod.github.io/howto/#/ https://marketplace.visualstudio.com/items?itemName=rafaelmnatali.docsascode https://marketplace.visualstudio.com/items?itemName=rafaelmn... https://www.synesthesia.co.uk/tag/docsascode/ https://www.synesthesia.co.uk/tag/docsascode/
  - kyawzazaw 1y ago
    Yup, Docs as Code is the more well-known phrase. https://www.writethedocs.org/guide/ https://www.writethedocs.org/guide/ See 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
  - johnathandos 1y ago
    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.)

kazinator 1y ago

docs is plural. You can't have a plural in a noun phrase, other than in he head position. For instance OK, no plurals: law school entrance test OK, head plural: law school entrance tests ?? non-head plural: law school entrances test

HumanOstrich 1y ago
Interesting. Can you provide some source(s) for this rule?
- eru 1y ago
  Especially since people like to play fast and loose with things like plurals in set phrases. See eg https://www.youtube.com/watch?v=AxlzkJAK1BM&t=22s https://www.youtube.com/watch?v=AxlzkJAK1BM&t=22s
- kazinator 1y ago
  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.
simonw 1y ago
"Docs" is short for "documentation", not "documentations".
- PhilipRoman 1y ago
  It's kind of its own thing at this point, people write "design doc" in singular so "docs" could very well be short for "documents".
  - hunterbrooks 1y ago
    Bingo - it’s colloquially
- TeMPOraL 1y ago
  "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".
  - kazinator 1y ago
    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).
- kazinator 1y ago
  https://news.ycombinator.com/item?id=43928303 https://news.ycombinator.com/item?id=43928303
jstanley 1y ago
"law schools enter test"
- kazinator 1y ago
  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].
  - jstanley 1y ago
    In "docs like code" the first noun is plural. Your examples were pluralising other words.
    - kazinator 1y ago
      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".)

MathMonkeyMan 1y ago

time flies like an arrow

3dprintscanner 1y ago
And fruit flies like a banana

dcminter 1y ago

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.

DeborahWrites 1y ago

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.

lproven 1y ago
> it's a widely-used term/practice in tech writing But it's not. You have got the key phrase wrong! It's Docs as Code. There are whole websites devoted to it: https://docsascode.org/ https://docsascode.org/ 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". https://docascod.github.io/howto/#/ https://docascod.github.io/howto/#/ https://marketplace.visualstudio.com/items?itemName=rafaelmnatali.docsascode https://marketplace.visualstudio.com/items?itemName=rafaelmn... https://www.synesthesia.co.uk/tag/docsascode/ https://www.synesthesia.co.uk/tag/docsascode/
- kyawzazaw 1y ago
  Yup, Docs as Code is the more well-known phrase. https://www.writethedocs.org/guide/ https://www.writethedocs.org/guide/ See 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
- johnathandos 1y ago
  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.)