For instance
OK, no plurals: law school entrance test
OK, head plural: law school entrance tests
?? non-head plural: law school entrances test
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.
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).
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".)
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.
But perhaps I need to explain this up top, rather than hoping people will hang in there until the explanatory section.
But it's not. You have got the key phrase wrong!
It's Docs as Code.
There are whole websites devoted to it:
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://marketplace.visualstudio.com/items?itemName=rafaelmn...
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
I am not saying you're wrong. I'm merely reporting my own experience.
I suppose I was trying to give the perspective of someone doesn't have a problem with authoring a markdown document for example... and bringing myself back to the reality that for most people authoring a document with any sort of formal (rigid, to be interpreted by machine) syntax is unfamiliar.
Now I feel physical pain every time someone sends me documentation in Word format since I know there are at least five diverged versions floating around, with no easy way to compare them (Word diff is stuck in 20th century), full of embedded diagram PNGs that are impossible to update unless you were the author and inconsistent styling on top of that.
The idea of using the same tools to manage your docs as you manage your code only makes sense if you understand what tools you use to manage code! If you don't -- if your main experience with documentation tooling is Word, or maybe MadCap stuff -- that's a really huge leap to make.
For example, "executable documentation" lets you run automated tests on your markdown files, keeping content fresh.
some links:
- https://github.com/MicrosoftDocs/executable-docs
- https://simonwillison.net/2018/Jul/28/documentation-unit-tes...
I can't parse the title or the first sentence.
Does she mean doc-like code?
Docs like code is a single term, maybe capitalization or dashes would help
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.
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.
For industrial controller software, esp distributed systems, there is a precedent of the standard IEC 61499.
One of the key components is the concept of an "Executable Specification", which may sound like unachievable BS, but if you are mainly doing state based systems, can be achieved by using state machines and working within a certain methodology/Activity framework.
I even wrote my own desktop application in PyQt specifically to satisfy requirements of 61508/61511 and the local burner code AS3814. The combustion and process engineers used this to specify (and verify by simulation, all within the tool) the exact exhaustive and unambiguous behavior for the machines (burner systems). As well for every state and transition condition attach a narrative about why it was like it was, with references, diagrams, attachments of manuals and datasheets etc.
Once all was decided, press the button, makes code, makes a documentation specification and compendium, and gives a level of traceability that is suitable for SIL 3, better accuracy, the systems guy (programmer) did not have to be a combustion engineer as well, because usually the crappy narrative type spec is always inadequate.
For certain types of code, this is the way of the future, and for things like rail and other super critical safety functionality, allows easy translation for application of formal methods to verify no unreachable conditions etc etc etc.
I had many colleagues that were initially in disbelief of the complexity but certainty of arbitrary functionality that was able to be specified with various hierarchal structures of state machines, as an executable specification
Fairly cool, but it requires Xcode, to work properly. It doesn’t really have a decent “export” capability, for things like GitHub Pages. There’s a fairly awkward way prescribed by Apple, that is annoying AF, and breaks easily, so I don’t usually bother. I’ll use Jazzy Docs to produce the GH Pages output.
I would love it, if GitHub would parse docc artifacts for GH Pages, but it’s probably too much of a pain to do.
I can see the use and value of it. The thing that I found really confusing was seeing "Docs Like Code". I've never really heard it said that way, and seeing it written down with that capitalisation kept me thinking that I was reading a sales tutorial for some SaaS pipeline integration offering.
It would have all clicked immediately to me if it was called "Docs as Code" and made a link to concepts like infrastructure as code, config as code or everything as code.
I think one thing to consider mentioning if you're targeting this at non-devs, Docs as Code is very much a case of: "to the person with a hammer, everything is a nail", meaning to the person without the hammer (non-devs), this is never going to seem like an easy, sensible or intuitive approach, even if it is comfortable for devs. Normal humans don't generally need to know about or do docs as code, because it doesn't make sense to them and is not efficient for them to produce.
So if you find yourself in a position of having to explain this a lot to non devs, you should perhaps ask "is it easier for all the non devs to learn to be devs to update the docs? Or is it easier to change our docs platform to something usable by non-devs?"
A decade ago 'docs like code' was an exciting invitation to work alongside developers, adopt their practices, and get closer to how the sausage was being made.
Today anything 'like code', but particularly prose, is right in the crosshairs of AI.
While people who can leverage AI are a bigger threat to your job than AI alone, in this case those people are developers. When developers, who hold all of the context of software functionality in their head, can interact with an LLM to draft docs, test them against validation and style rules, and publish them, they just will.
DeborahWrites•10mo ago
This guide is for the people who read that paragraph and wished it came with a glossary. This is docs like code for people who don't know what git is and have never installed VS Code.
dcminter•10mo ago
DeborahWrites•10mo ago
It's obviously not going to get someone up and running: it's not a hands-on practical guide. But there are already quite a lot of those out there (for instance, most static site generators have acceptable getting started docs) The aim is to provide the missing conceptual info that's usually assumed by the creators of tools, but that not all tech writers have. Ideally, it should make them feel more comfortable following, say, an intro to git tutorial, because they have a bit more context/explanation backing them up.
dcminter•10mo ago
bonzini•10mo ago
None of them had a developer background, I don't see why they wouldn't be able to do the same with Markdown and a pull request instead.
[1] Nope, no version control :) though there were three separate domains for unstable/test/prod (test/prod shared the database too, unstable didn't).