31–40 of 61 posts
Deborah Writes ... ESL-level gibberish. 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
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.
But perhaps I need to explain this up top, rather than hoping people will hang in there until the explanatory section.
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.
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.
This is.. about teaching people how to write text documents?
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.
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
Earlier quoted context omitted.
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
"Docs" is short for "documentation", not "documentations".
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?"
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.
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).
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 C…