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.
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.
The terminology used is very confusing. There should be a better name for this than 'docs as code'.
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...
Deborah Writes ... ESL-level gibberish.
I can't parse the title or the first sentence.
Does she mean doc-like code?
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.
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.
So this is WYSINWYG.
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.
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.
Not really. As a techie I prefer a CMS over say Jekyll.
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?
time flies like an arrow