4 ms·
Docs as Code at Linode (2020)
- fesc 3y agoI am a little bit disappointed. This is just plain old static site generation? 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.
- remoquete 3y agoSee https://www.writethedocs.org/guide/docs-as-code/ https://www.writethedocs.org/guide/docs-as-code/
- MoreQARespect 3y agoLike this https://github.com/hitchdev/hitchstory https://github.com/hitchdev/hitchstory ?
- rob74 3y agoSo 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/ 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.
- pessimizer 3y agoIf 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.
- jagged-chisel 3y agoI think I’d call that “docs in/from/are code.” “Docs as code” couldn’t be more literal and clear when treating doc as if they were code.
- aziis98 3y agoThe title is a bit misleading, thought this was about infrastructure as code but they just use linters and CI/CD on documentation. Still interesting to see that they take great care of documentation just as another fundamental part of their systems.
- gabereiser 3y agoTitle is on the mark. See https://www.writethedocs.org/guide/docs-as-code/ https://www.writethedocs.org/guide/docs-as-code/
- leonheld 3y agoIn 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... [0]https://docusaurus.io/ https://docusaurus.io/
- KnobbleMcKnees 3y agoI 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. I need to find an excuse to use it again.
- spondylosaurus 3y agoCan 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.)
- synergy20 3y agomy 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.
- osxman 3y agoBummer: there is (unfortunately) no Linode anymore…
- Supermancho 3y agoLinode was purchased by Akamai. While https://www.linode.com https://www.linode.com is still functional, the writing is on the wall.
- jasonlotito 3y ago"Linode’s technical writing team" 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.
- notorandit 3y agoCODE? 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.
- remoquete 3y agoThis 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.
- deleted 3y ago[deleted]
- spondylosaurus 3y agoYep, 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.
- euroderf 3y agoor Microsoft document formats.
- Longwelwind 3y agoWhether 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.
- kodah 3y ago> 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.
- remoquete 3y agoAgain, the point is not to write code to write docs. See the other comments.
- kodah 3y agoThat 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.
- remoquete 3y agoOf 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. ;-)
- splittingTimes 3y agoGreat 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. === [1] https://asciidoc.org/ https://asciidoc.org/ [2] https://antora.org/ https://antora.org/