Robert Mustacchi

I'm using ASCII doc for everything. So our doc site is built on ASCII doc, our RFD site, and the blog posts on the marketing site are all ASCII doc.

So what we have there is, and that in tandem with our design system, our colors, our typography, all of that stuff is unified across both kind of product and internal sites, which is unusual because usually you have your product design system and then you have some other designers who kind of are off like playing in the sandpit, doing like the website, doing whatever they want. I'm doing both.

So I can have a unified system. And what it means is... when we, when I, when I do the styling for the kind of RFD site it's shared across all these places. So I can justify spending a bit of time on these things because, um, Because it's so useful.

So you, Hey, don't, don't blame me. Don't blame me for that.

Really briefly on the stuff that we've made for it. So there is a... My main issue of ASCII Doc is that there is no kind of native... like Rust or JavaScript library for processing it, there is a JavaScript library which is transpiled from Ruby. And so kind of making changes or seeing how it works in another hood is kind of, is sometimes challenging.

And then it kind of, there's a bunch of assumptions on the way that it works. Like it assumes that you're going to process a whole ICO document in one go, top to bottom, right? which makes sense if you're processing it locally. In my case, I kind of worked on a React render of ASCII doc.

And essentially what I do is I take this ASCII doc tree and I work through it and I render kind of each part as kind of React components. If you're not doing that, you have to create a renderer where you're returning a string. So you want to render an image, you return a string, and you drop in.

You're accessing the attributes, and you're swapping stuff in and out, which isn't ideal, especially if you want to do some more interactive things like our images. It gets complicated because we're using signed images that come from GCP. We want a little light box. There's some other kind of features where if you want any kind of interactivity, that model doesn't work.

So we wrote a React renderer for that. But then you kind of, React doesn't run once, top to bottom, and you have issues. The big issue that I spent way too long on was every time you render a piece of content, with a footnote in it, it assumes that it's a new footnote.

So every time it's re-rendering that piece of text with a footnote, your number of footnotes is increasing, increasing, increasing up on the page. So those things are kind of challenging. And we've found ways around them. And I think like I have a, each one of these versions is motivated by kind of a piece of functionality that we want.

So one thing I've been playing with recently is creating this intermediary format for ASCII doc. So I take, I go through the tree, I process it, I turn it into like a JSON object that can be passed easily from the server to the client. And that means that you can kind of pre-process it on the server and then you're not shipping like these big

this like two megabyte, uh, client library just to handle it on the front end. Um, but, and, and, and the reason why that is important is let's say we're in the, we're in the, then the console. And then, and this is a big aspiration of Robert's is if we, if we want documentation that exists within the console, it doesn't feel justified to ship this big ASCII doc JS, um, library in the console.

Cause that kind of is a bit bloated. Um, but I think, uh, kind of working on experiments so that we can have dynamic documentation. Maybe if you're kind of working on, uh,

repairs and kind of swapping components then then we have that without needing to um do yeah kind of do all this stuff so yeah it's it's it's interesting um it's a it's a bit of a challenge at times but uh yeah the versatility is the kind of is the is is the the thing that's great and the thing that kind of trips me up sometimes

That was a, I think, I guess I think to, to, to begin, I think there's, there's, there's something around like the accessibility of this stuff. Oxide has always been like, um, really kind of engineering driven. Um, and engineers are really familiar with GitHub and that's really easy for them.

But, uh, I think if you want this process to be used outside in kind of like kind of sales and operations and, and, and, and design, then, um, really, you have to make this stuff as accessible as possible. And we're not there. And I think we're working towards it. But getting GitHub discussions directly into the RFD site felt like a big step towards that.

Essentially, what's nice about the GitHub discussions is you're leaving line comments. And one great feature of our ASCII doc is that you can trace you can kind of, given a line in an ASCII doc document, you can get the, no, in the return, in the render document, you can get the associated line number.

So what it meant is we could query the GitHub API, get all of the comments, kind of collect them in,

kind of a format that can be kind of rendered easily which which is which is pretty kind of tricky to begin with um and then we go through sort of line by line and and we we position them alongside the content directly if they're still relevant um and then we have this sidebar which kind of you can see the kind of full canonical discussion and you can kind of jump to the the relevant part um but yeah just that little bit of kind of being able to associate the original

document with the rendered document uh was enough that we could pull like from the api people's avatars and we can kind of have this little this module that people can click on and can and and and view um yeah and i think my kind of first experiment was this super ugly way of getting like a little avatar alongside the text but that yeah that felt kind of a real um kind of a huge improvement