David Crespo

had come along the way like i don't remember if we had something as formal for manta i think i wrote up a bunch for the fabrics stuff in like 2013 2012 yeah and but they were just kind of like one-off documents that we would just kind of store and toss on you know the like local http server for folks to build to see and then i guess we eventually had manta we tossed it in there but

I think they've been sands of time.

Very well. Thank you.

Yeah, I think, you know, But definitely a bunch of things we're trying to figure out is what is the content? How do we section it? I was going back and looking at the prototype we had for the RFD set at Joyent. And it's literally just like, OK, there's a title, and that's it.

And I think sometimes that not even having like, not that there's too many more sections than what we have at Oxide, but I think having a little bit there

helps um and then i think the method of discussion it's also something that we're trying to iterate and figure out you know what's the right way to do it um yeah you know some of it was just kind of like ah there's an issue or you know some folks discuss in chat or sometimes we had an email thread and that worked okay ish um i don't know yeah i mean pros and cons there the github

GitHub PR today is differently painful because of GitHub more so than anything else.

Yeah, and I think some of the other bits here, you know, locating everything in a repo makes it very easy to see what's changed over time. The discoverability was big, and then We ended up with Markdown initially mostly because, I don't know, it was the thing to do du jour. It was easy to see rendered.

Trent had his Python Markdown 2, which we had used for a lot of docs and other things historically.

I mean, probably. Given how we're weird on everything else, right? Yeah, part of this evolution I think came from a few steps. I mean, once you're in the non-WhizzyWig world, so once you're not in a Word or Google Docs, then there's kind of two challenges. One, and

This may be my own fault, but it is very hard in the markdown days, particularly in 2012, 2015, to see a rendered markdown doc, per se, locally without pushing it somewhere up. And that, for me, was just my own mental foible of wanting to see, hey, does this render correctly before I push it?

It's like tough, tough and fair. Uh, and then I think the other, the other thing that we kind of saw as we were getting down, um, And I think the first Joyent, so actually Alex Wilson, who wrote RFD1, was the first one to use ASCII doc in an RFD at Joyent. Oh, really? Yeah, he was the one who found it and pointed us towards it. And I want to say it was probably for RFD77 there.

And once you kind of got to, you know, I think one of the Markdown strengths was, you know, it was very simple. Uh, one of Markdown's weaknesses is like, if you want to create a table, there's still probably like 20 different ways to create a table. And if you want a table of contents, like, you know, God forbid that, uh, you're, you're really on your own. And so the little bit of additional, um,

syntactic features that we got out of asciidoc was kind of why for complex documents we want to move there you know easy knowing that there's easy ways to link between different sections or other things or kind of a bunch of the other features and you know there's a bunch of features we didn't even use back then that uh now so our colleagues like uh ben knacker is using in the oxql rfd so he could easily do call outs or other things so i i found it to be a you know

Easy to get something basic that looks pretty good. And then if you need to go complex, you had that capability. Whereas with Markdown, you were kind of constrained by the Markdown renderer. And no two renders were going to do it the same way.

I just always used ASCII doctor and just pulled up the HTML file. Um, and just use that. And it was pretty good. It had default CSS too, which just meant you could use it and toss a document somewhere, and people could see it. And it looked fine on both mobile and not mobile, which was really nice as someone who doesn't want to think about CSS.

Yeah.

Yeah, specifically for the Gimlet hardware sled.

Sure. So, I mean, I think to kind of talk about how we use RFDs for Cosmo, it helps a little bit to talk about RFDs for Gimlet along the way. So when we were developing Gimlet, I'd say, you know, this was a time when the first RFDs were in, there's maybe what, 12 of us, 15 of us. And this is before most of the team has started. I mean, this is mid 2020, maybe early.

So a lot of it was us trying to separate out the specifics of what was important for socket SP3 or specifics for this particular AMD aspect versus what is it we generally want. So a lot of things are split up in those early RFDs in part because of that. We had something about what does PCIe hot plug look like? What are our goals and constraints?