Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Docs like code in basic terms

deborahwrites.com

Post reply on HN
Print view View original

51–60 of 61 posts

Re: Docs like code in basic terms

#51

Post by kazinator »

TeMPOraL wrote: post #37
simonw wrote: post #22

Earlier quoted context omitted.

"Docs" is short for "documentation", not "documentations".

"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).

Re: Docs like code in basic terms

#52

Post by kazinator »

jstanley wrote: post #24
kazinator wrote: post #16

Earlier quoted context omitted.

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

"law schools enter test"

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].

Re: Docs like code in basic terms

#53

Post by johnathandos »

lproven wrote: post #46
DeborahWrites wrote: post #32

Earlier quoted context omitted.

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 t…

> 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/ 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…

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.)

Re: Docs like code in basic terms

#54

Post by kazinator »

simonw wrote: post #22
kazinator wrote: post #16

Earlier quoted context omitted.

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

"Docs" is short for "documentation", not "documentations".

https://news.ycombinator.com/item?id=43928303

Re: Docs like code in basic terms

#55

Post by jstanley »

kazinator wrote: post #52
jstanley wrote: post #24

Earlier quoted context omitted.

"law schools enter test"

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].

In "docs like code" the first noun is plural. Your examples were pluralising other words.

Re: Docs like code in basic terms

#56

Post by kazinator »

jstanley wrote: post #55
kazinator wrote: post #52

Earlier quoted context omitted.

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].

In "docs like code" the first noun is plural. Your examples were pluralising other words.

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".)

Re: Docs like code in basic terms

#57

Post by kazinator »

HumanOstrich wrote: post #18
kazinator wrote: post #16

Earlier quoted context omitted.

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

Interesting. Can you provide some source(s) for this rule?

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.

Re: Docs like code in basic terms

#58

Post by keybored »

kazinator wrote: post #15

Deborah Writes ... ESL-level gibberish. I can't parse the title or the first sentence. Does she mean doc-like code?

Skimming the text it seems okay. Relatively simple sentences (simple sentences are not necessarily good, depends on the complexity of the subject). A string of simple statements are used to continue the narrative. More complex sentences are built up with a few colons (should be semicolons) and a stringing together of commas that I personally will never get used to.

Re: Docs like code in basic terms

#59

Post by branko_d »

lproven wrote: post #44
branko_d wrote: post #23

Summary: 1. Write some docs in a text editor. 2. Using git, send your new docs to GitHub. 3. Follow some steps on GitHub to finish adding your new docs to the site. 4. A process runs which takes your changes, builds everything into a website (using the static site generator), and deploys it to a server.

> builds everything into a website No! This is not about websites. It's about building manuals. The result could be a book, an ePub, a PDF, or -- almost incidentally -- a website.

The above was copy-pasted from the article.

Re: Docs like code in basic terms

#60

Post by DeborahWrites »

KolmogorovComp wrote: post #48

Tangential, but does anybody know a frontend more friendly than GitHub for non-technical persons to navigate through doc history? More like a wikipedia page history.

Some knowledge base or wiki tools build this in, but I don't know of a friendlier alternative for text-based formats (markdown etc.) Would love to hear of it if you find one . . . I suspect it would need to be git or something similar under the hood though?
Post reply on HN