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...
For instance
OK, no plurals: law school entrance test
OK, head plural: law school entrance tests
?? non-head plural: law school entrances test
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?"
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.
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.
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).
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...
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
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
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.
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.
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.
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.
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.
