Showcasing a hub for knowledge sharing and collaboration that drives our decision-making process.
Overview
The article discusses the implementation and significance of Requests for Discussion (RFDs) at Oxide, detailing their role in architectural and design decisions. It highlights the internal RFD site developed to enhance collaboration and user experience, showcasing features like full-text search, inline PR discussion, and inter-RFD linking.
What You'll Learn
1
How to utilize the RFD process for architectural decisions
2
Why inline PR discussions enhance understanding of RFDs
3
How to implement full-text search using Meilisearch
Key Questions Answered
What are Requests for Discussion (RFDs) and their purpose?
Requests for Discussion (RFDs) at Oxide serve to document architectural and design decisions, allowing for both timely discussions of rough ideas and a permanent repository for established ones. They are essential in guiding the development processes and tools used within the organization.
How does the internal RFD site improve collaboration?
The internal RFD site enhances collaboration by providing a better reading experience, supporting full-text search, and allowing inline discussions of pull requests. This streamlines the process of accessing and discussing RFDs, making it easier for users to engage with the content.
What features does the RFD site offer for navigation?
The RFD site features a directory sorted by last updated, full-text search powered by Meilisearch, inline PR discussions fetched via the GitHub API, inter-RFD linking for context, and a jump-to menu for quick access to specific RFDs. These features significantly enhance user experience and accessibility.
Technologies & Tools
Some links below are affiliate links. We may earn a commission if you make a purchase.
Search Engine
Meilisearch
Used to power the full-text search feature on the internal RFD site.
API
Github API
Utilized to fetch pull request discussions for inline comments.
Javascript Library
Asciidoctor.js
Employed to map comments from GitHub to the rendered RFD document.
Web Framework
Remix
Used for implementing deferred responses to improve page load times.
Key Actionable Insights
1Implementing inline PR discussions within RFDs can significantly improve user engagement and understanding.By displaying comments alongside relevant document sections, users can grasp the context of discussions without navigating away, fostering a more cohesive understanding of the RFD.
2Utilizing a full-text search feature can streamline the process of finding relevant documentation.With Meilisearch, users can quickly locate RFDs, making it easier to access information and enhancing productivity.
3Creating inter-RFD links can improve contextual understanding and navigation between related documents.This feature allows users to see previews of related RFDs, facilitating better comprehension of how different discussions are interconnected.
Common Pitfalls
1
Cloning a Git repository and running scripts to create an RFD can be cumbersome for new users.
This complexity may deter participation in the RFD process. Simplifying the creation process through a web app with an embedded text editor could enhance accessibility and encourage broader collaboration.