At Oxide, RFDs (Requests for Discussion) play a crucial role in driving our architectural and design decisions. They document the processes, APIs, and tools that we use. The workflow for the RFD process is based upon those of the Golang proposal process, Joyent RFD process, Rust RFC (Request for Comments) process, and Kubernetes proposal process. To learn more about RFDs and their process, you can read this post.
Similar to RFCs, our philosophy of RFDs is to allow both timely discussion of rough ideas, while still becoming a permanent repository for more established ones.
Oxide RFDs are essentially a collection of AsciiDoc documents, collected in a GitHub repo. They can be quickly iterated on in a branch, discussed actively as part of a pull request to be merged, or commented upon after having been published.
Whilst a repo is a useful storage and collaboration tool, there are a number of drawbacks: it doesn’t provide the best reading experience, is limited in terms of AsciiDoc support, and is challenging to share externally. To address these issues we developed an internal RFD site. This post serves as showcase for that site and gives a brief look at some of its features.
RFD directory
Users land directly on the directory. By default it is sorted by last updated to give the user an idea of the RFDs that are actively being worked on.
Full-text search
Full-text search is powered by a self-hosted Meilisearch instance. The search index is automatically updated whenever an RFD is edited. Users can access the search function through the navigation menu or by using the hotkey CMD+K and can quickly navigate through the search results using their keyboard whilst previewing the associated RFD.
Inline PR discussion
The discussion surrounding an RFD is crucial to understanding its context, but until recently users would have to open the associated pull request in a separate tab to view its comments. To improve this experience, we’ve implemented a feature that uses the GitHub API to fetch the pull request discussion and display the comments that are still actively attached to a line alongside the part of the document they relate to.
We achieve this by using the getLineNumber function in asciidoctor.js, which allows us to map the raw line number of the comment (from the GitHub API) to the nearest block in the rendered document. While this method may not pinpoint the exact line, it is usually accurate enough.
To avoid slowing down page load times, we use the Remix deferred response feature to stream in the comments asynchronously, holding only for the critical RFD content to finish loading.
const rfd = await fetchRfd(num, user)
if (!rfd) throw resp404()
// this must not be awaited, it is being deferred
const discussionPromise = fetchDiscussion(rfd.discussion_link, user)
return defer({ rfd, discussionPromise })Users can access the full discussion of an RFD at any time by opening a dialog regardless of their current location on the page. This dialog also provides the ability to jump directly to the line that is being commented on.
Inter-RFD linking
When an RFD document references another RFD within its content, the user can hover over the reference to see a preview of the title, authors, status, and the date of the last update. This makes it easy for users to understand the context and relationship between different RFDs, and quickly access the related documents.
Jump-to menu
For users who know the title or number of the RFD they want to view, a menu can be opened by pressing CMD+/ from any page on the site. This menu allows users to quickly filter and select the desired RFD using their keyboard.
Upcoming
The internal tooling around RFDs is always improving, and as it does, we hope that the way we collaborate will also improve. There is still work to be done in terms of discoverability of documentation, such as adding more tools to filter and tag RFDs, and creating collections of documents. This will make it easier for new employees to get up to speed, and make it easier to manage the challenges that come with a growing team and an increasing amount of documentation. Having a better understanding of the whole stack is valuable, as it allows us to better understand the impact of our work on other parts of the product.
Additionally, we need to consider how we can make this process more accessible to everyone. Writing an RFD currently requires cloning a Git repo, running a script, committing, pushing, and making a PR. We are thinking about how to do this all through the web app with an embedded text editor. Oxide is and will continue to be an engineering-led organization, but RFDs are not just for engineers. Making it easier for everyone to create and collaborate on these documents will result in richer conversations.