Great article on the topic.
Biggest takeaway is how they added linters and link checkers to the toolchain.
We currently try to establish something similar on our end using AsciiDoc [1] as fileformat, Antora [2] to build the site and hosting on Azure storage.
AsciiDoc has a bit more features compared to Markdown which allows for a richer presentation of the docs.
Biggest difference is that Linode has the docs in a separate repository. Not sure if it is a limitation of their toolchain or a deliberate decision.
Antora allows you to have the project documentation in the actual project repositories. It then pulls the docs from all the different repos together to build the site. This also allows you to have the released product versions go in-synch with the docs versions. Antora builds each version of the product as part of one site. The reader can explore different product versions or navigate between pages across versions.
In the same vein, docussaurus[0] has been a pleasure to work with (not affiliated in any way). It's snappy, has a solid text interface, the search works etc...
I really enjoyed working with docusaurus. Being able to embed live examples of the described SDK to initialise and play around with was excellent and helped us achieve really fast adoption from other teams in our org.
Can I ask if you were using any plugins or other tools for your SDK docs? We're coming up on a similar need in our own Docusaurus site soon and I'm curious if people use any dedicated methods to format/publish their SDK documentation. (My quest to find "an OpenAPI-esque plugin but for things that aren't REST" hasn't turned up much yet.)
By "docs as code" I expected something like programmatically verifying that the code examples compile, maybe even spinning up VMs and testing that the example commands lead to the expected output.
So basically the treat their docs as if it's code, i.e. use version control, CI etc. for it, but it's still not really code.
For me, actual "docs as code" would be more like CUE (https://cuelang.org/) - a language with which you can write definitions for e.g. an API, and then use this code to generate docs and validate your API output against.
If we're going to be persnickety, that your "actual docs as code" sounds more like "code as docs." Because you're writing code and turning it into docs. "Docs as code" seems more like if you wrote docs and treated them as code.
This is the key. Someone has ownership over the docs. This is their job. If you expect programmers to invest into good docs, you need to measure them on it. Otherwise, you are hoping they write good docs. If you don't value the docs they write, they probably won't spend time on it. Like most people, they will put effort into what gets measured at performance review time.
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.
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.
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.
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.
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?
> Docs as code is a methodology where the tools you use for writing documentation are the same as the tools used for writing software. This includes:
Using version control software
Writing plain-text documentation files
Running automated tests
Practicing continuous integration and continuous delivery
To me this is version controlled and tested docs. There's little code to it from what I can see. Docs as code is like in Go where you annotate a function and it's documentation is rendered into markdown. Some of these systems can be rigged up to be quite fancy, like generating OpenAPI specs from annotations and signatures.
It is still cool to see what goes into managing a knowledge base of that size and scale. I'd be interested in what they use as front matter structure to organize everything.
That would also be the point of what I described. You're not writing code, you're writing comments. Those comments are consumed by a structured static site generator. What linode does has nothing to do with code other than using a markdown linter and a pipeline.
Of course docs are code. The fact that English still doesn't have a compiler to machine code doesn't mean it won't move registers in your brain. There's already a pretty good interpreter in our heads and it's called Wernicke's area. ;-)
my old friend doxygen came to mind, very useful for OOD code base as it draws the dependency graph, but, it does not do Restful API etc in the modern web days.
We currently try to establish something similar on our end using AsciiDoc [1] as fileformat, Antora [2] to build the site and hosting on Azure storage. AsciiDoc has a bit more features compared to Markdown which allows for a richer presentation of the docs.
Biggest difference is that Linode has the docs in a separate repository. Not sure if it is a limitation of their toolchain or a deliberate decision.
Antora allows you to have the project documentation in the actual project repositories. It then pulls the docs from all the different repos together to build the site. This also allows you to have the released product versions go in-synch with the docs versions. Antora builds each version of the product as part of one site. The reader can explore different product versions or navigate between pages across versions.
===
[1] https://asciidoc.org/
[2] https://antora.org/