Earlier quoted context omitted.
"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 like code in basic terms
41–50 of 61 posts
Re: Docs like code in basic terms
#42Summary: 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. :)
Re: Docs like code in basic terms
#43Deborah Writes ... ESL-level gibberish. I can't parse the title or the first sentence. Does she mean doc-like code?
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!
Re: Docs like code in basic terms
#44Summary: 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.
> 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.
Re: Docs like code in basic terms
#45Earlier quoted context omitted.
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 alr…
Great that you road-tested it! Real world data is always going to be higher quality than my drive-by opinion!
Re: Docs like code in basic terms
#46I 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.
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 t…
> 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:
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...
Re: Docs like code in basic terms
#47This 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.
Re: Docs like code in basic terms
#48Tangential, 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.
Re: Docs like code in basic terms
#49What about Sphinx built documentation?
Re: Docs like code in basic terms
#50Earlier quoted context omitted.
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 t…
> 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…
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