Docs like code in basic terms | Hacker News Reader

Docs like code in basic terms

deborahwrites.com

66 pointsDeborahWrites60 comments

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.

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?

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

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 "documentation", not "documentations".

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

Bingo - it’s colloquially

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

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

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

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

time flies like an arrow

And fruit flies like a banana

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.

> 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, 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.synesthesia.co.uk/tag/docsascode/

Yup, Docs as Code is the more well-known phrase.

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

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.

It took me a read or 2 to really make sense of this.

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?"

Yeah, if your primary contributors aren't already comfortable with version control, you likely want to choose another toolset.

Most guides to docs like code, even the ones for non-devs, assume you have some developer knowledge: maybe you're already using version control, or you've encountered build pipelines before, or you're working alongside developers.

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.

This seems well intentioned, but ... have you actually put this in front of a non-programmer and got them to try to create documentation using it? I suspect it's got more speedbumps left in it than you think.

Very valid question. I have tested it a little! I wrote it because a less technical tech writer was asking me a ton of questions, and he found it helpful. I also got a non-technical marketing person to review it, and she said she was able to learn a lot from it (those are the two people I thank in the intro)

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.

Great that you road-tested it! Real world data is always going to be higher quality than my drive-by opinion!

In the early 2000s I was working in a webdev team where editors worked on the raw HTML (some with the help of Macromedia Dreamweaver, some simply with Notepad++) and pushed it to the httpd root via SFTP[1].

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

Often the key is setting up an "executable documentation" environment.

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

The terminology used is very confusing. There should be a better name for this than 'docs as code'.

"Docs' abode's the code"

The concept works better for somewhat regulated environments, I have used it for functional safety.

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

Deborah Writes ... ESL-level gibberish.

I can't parse the title or the first sentence.

Does she mean doc-like code?

https://www.writethedocs.org/guide/docs-as-code/

Docs like code is a single term, maybe capitalization or dashes would help

Capitalization would probably be a good idea, based on the comments here! Thanks!

This comment goes against the spirit of respect that should reign on HN. Please contribute only if you've anything remotely interesting to say -- thank you!

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.

This works amazingly well for regulated software markets such as medical devices that need a lot of review/approval and traceability. Markdown is much more AI and script-friendly yet still layman readable. The workflow is significantly faster than industry standard tools like Windchill which are like git with a 1985 GUI in front of it.

yeah, see my level 1 comment

I’ve been using Apple’s docc[0]. It mostly just means that I write my code docs the same way as I always have (Doxygen markdown style), but it has an additional “compile” step, that produces a build artifact that integrates into the Xcode Documentation engine. You can make a pretty rich experience, with things like images and videos, all linked directly to your code.

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.

[0] https://www.swift.org/documentation/docc/

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.

The post is for non-devs. :)

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

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?

I think from reading that, docs like code is roughly something like using Github and CI to manage docs rather than say WordPress or Confluence?

Yeah, exactly. If you're a developer, it can take a little bit to figure out that "docs like code" is a really strange concept to lots of non-developers.

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.

What about Sphinx built documentation?

This is.. about teaching people how to write text documents?

Yes exactly. People who write text are not going to be excited about making saving their text such an extraordinarily complicated task, nor will they think it’s interesting in its own right.

This is a dismissive comment, as is the parent. The post is about a well known software documentation paradigm.

Not really. As a techie I prefer a CMS over say Jekyll.

I wasn't trying to be dismissive, only in line with the explicit call outs for simplicity from the author.

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.

Believe it or not, when I started to learn programming I had no idea that "plain text" was a thing, since I had only been taught Word at school. So I think this is very valuable for many people who work in tech adjacent areas.

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.

Oh. I thought doctors liked code.

So this is WYSINWYG.

This article is aimed at non-technical writers of documentation.

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.

Reply on news.ycombinator.com