Docs like code in basic terms
42 comments
·May 5, 2025azdavis
DeborahWrites
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.
dcminter
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.
kazinator
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
Interesting. Can you provide some source(s) for this rule?
eru
Especially since people like to play fast and loose with things like plurals in set phrases.
simonw
"Docs" is short for "documentation", not "documentations".
PhilipRoman
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".
TeMPOraL
"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".
jstanley
"law schools enter test"
1dom
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?"
DeborahWrites
Yeah, if your primary contributors aren't already comfortable with version control, you likely want to choose another toolset.
DeborahWrites
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.
dcminter
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.
DeborahWrites
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.
bonzini
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).
ChrisMarshallNY
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.
billfruit
The terminology used is very confusing. There should be a better name for this than 'docs as code'.
euroderf
"Docs' abode's the code"
airbreather
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
gsmethells
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.
airbreather
yeah, see my level 1 comment
branko_d
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.
theletterf
The post is for non-devs. :)
pella
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...
kazinator
Deborah Writes ... ESL-level gibberish.
I can't parse the title or the first sentence.
Does she mean doc-like code?
theletterf
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!
PhilipRoman
https://www.writethedocs.org/guide/docs-as-code/
Docs like code is a single term, maybe capitalization or dashes would help
DeborahWrites
Capitalization would probably be a good idea, based on the comments here! Thanks!
foobahhhhh
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?
ddulaney
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.
meindnoch
Oh. I thought doctors liked code.
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.