Hacker News Reader

Comment by notorandit | Hacker News Reader

CODE? You said "CODE" again? C'mon! :-D

The fact that you store something in a VCS, that you pipe it through some "lint, test, deploy" pipeline doesn't make it "code".

Nowadays they call anything "code" just because you do VCS + pipeline. Most of the time it is (complex) configuration text files (like cloudformation and terraform) or some sort of documentation (like markdown).

When you can implement a generic Touring machine with whatever you call "code", then you can really call it "code", IMHO.

I use to say to my students (with a large amount of semplification), if you can implement a sorting algorithm with that, then it's code. Otherwise it is not.

View on HN

This is a dismissive position.

The point of "docs-as-code" is not "code that produce docs", but "docs treated as code", that is, versioned in a VCS and built using similar workflows as the code they document. It's also a way of bringing technical writers and developers together and collaborate more.

Yep, and "docs-as-code" is an established concept in the technical writing world. Ask almost any software tech writer[0] about docs-as-code and they'll know what you're referring to.

[0] Maybe barring the tech writers who are still stuck using FrameMaker and the like.

or Microsoft document formats.

Whether it's code or not that is being stored in the VCS is not really what matters. The idea is of X-as-Code is that you treat X in the same way that you treat code (VCSed, tested in a CI pipeline, deployed via an automated CD pipeline and not manually, ...).

Debating on the use of the words is wasted energy. Imo, what matters the most are the concepts behind them. The same can be said about the many discussions about server-less architecture.

Words do matter, as do the concepts behind them. We've been generating documentation through code for a long time. Go has an implementation of this and OpenAPI does as well. Docs as code seems to endear adjacency to code. Version controlling and linting things in a pipeline is a useful concept, though not particularly novel as far as static site generators go. Maybe "version controlled docs" would be a better term.

Words do matter indeed, and your usage of them is wrong.

What you described is docs _in_ code. The title is docs _as_ code, which means exactly as what the article describes, treating it as if it is code in pursuit of maintainability.

Totally agree. This code-mania needs to get to an end.

Of course you can start calling your mouse "a cat", your car "a mobility device" and yourself a genius. But reality won't easily follow.

anyway, https://www.writethedocs.org/guide/docs-as-code/ is the thing being referred to. go yell at Eric, though you'll be disappointed when he just graciously accepts the feedback and finds a way to incorporate it

It technically fits the broad definition of "code", besides the wordage "X as Code" conveys the meaning of treating X as if it is code by applying the same sort of tooling to maintain it (as if it were code).

I feel sad for your students (if you really have any) for having such obtuse teacher.

OK, here is a true code approach to generate wiki pages with embedded Mermaid sequence diagramms. https://github.com/Calpano/featdoc Feedback welcome.

If a document in plain-text provides instruction to a human on how to sort a set of things in a generic way, wouldn't this be implementing a sorting algorithm that runs on humans as a hardware platform?

If I say I'm using the sun as a clock, would you object because clocks have springs, screws and hands and suns don't have springs, screws and hands?

CLOCK?!

Reply on news.ycombinator.com