Hey Zane and the Netflix Team!
On behalf of the whole ReadMe team, we've really enjoyed working with you so far. We know you have a lot of requirements to make this successful, and we're committed to making this work for you and your team!
As a rule, we don't do custom work for customers. We host docs for thousands of large companies, from NVIDIA to Amazon to Apple, and it's not something that scales — we don't want to be beholden to another company's roadmap. That being said, I want to offer Netflix a large amount of custom development to satisfy your unique requirements.
While these features won't be available when you sign, we'll commit to delivering all blockers (P0) within 180 days. Additionally, for P1 and P2s, we will make reasonable efforts to either build or provide direct consultation to Netflix for the in-house development of workarounds or workflows to address all requirements specified below.
In order to deliver this, we will have dedicated engineers working on the Netflix account full-time. They'll be supported by the rest of the engineering team, and will be able to start on day one!
I know your internal Docusaurus platform is beloved, but we're ready and excited to fill those dinosaur-sized shoes!
Gregory Koberger
Founder, ReadMe
P.S. Don't worry, we will also send over a more legalease-y version of this document!
A centralized “documentation hub” that contains docs for multiple related products. Mostly static content + a few interactive, React-based flows.
Example: an internal Netflix component library
We will make it so that components can be imported from an external NPM package and used in MDX
Status: Not started
Similar to what you’d get with a CMS like swizzling in docusaurus. Define a custom layout and have ReadMe slot content into the right place.
See also: the swizzling feature in Docusaurus (full layout customization)
This is the one I'm a bit hesitant about, due to the scope of it (and lack of specificity). Our goal is to balance customization with simplicity, so that you can do what you want while benefiting from a nice out-of-the-box experience. That being said, while we can't commit to something exactly like swizzling (since it would require a full rearchitecture of our entire system), we've found we're quite customizable already and are very open to adding more ways to customize the layouts.
Status: Not started
Example: autogenerated API docs created during a monorepo build
Workaround: call the ReadMe create/update doc API during the build
Lifecycle hooks / GitHub action
This already exists! We have a tool called `rdme` that can help get auto-generated files into the right place, or we're happy to build out customized workflows via our API. Any limitations in our current systems, we're happy to address.
Status: Mostly ready
Documentation for a JavaScript libraries. Requires significant interactivity and integration with Netflix internal systems.
Docs colocated with packages inside a monorepo
While co-locating docs and code is something we care about, we don't ever want access to code directly for security reasons. Git (and GitHub) make it so that this is a technical limitation we can't overcome directly.
HOWEVER! We are working to make submodules completely seamless. Submodules are a bit annoying to work with by default, however we'll build out tooling to make sure the experience is (almost) equivalent to using a subfolder.
Status: Not started
Example: a GraphQL graph
Example: a back-end Java service
We can make this happen! We already have a GraphQL feature (which we will port over to Git for Netflix), and can build out a system that can pair a data format with an MDX component.
We're very open to how you'd want this implemented.
Status: Not started
Develop the docs locally and have local components live-reload when edited
User-facing interactive demos: a control panel for toggling component props
This is a great idea. While it's not on our roadmap yet due to prioritization, we'd love to build this out for Netflix. There's already some arguing internally who gets to work on it, since a few people think it'd be fun to build!
Status: Not started
Support a robust set of features for API References!
Including OAS files in ReadMe
This is where we really shine... displaying OAS files. So, we're confident you'll much prefer this to SwaggerHub's UI!
We already support OAS (which is what SwaggerHub outputs), so this should be done already!
That being said, if there's workflows you'd prefer (such as a deeper SwaggerHub integration), we can build something out or help with configuration options.
Status: Potentially done
Including Javadoc-formatted files in ReadMe
This might be a bit more difficult depending on the complexity of your Javadocs, however I believe we can help convert Javadoc to Markdown and build this out relatively easily!
Status: Not started
Get Netflix content into ReadMe!
Estimated volume: ~100 sites
This is something we do a lot, and have already started!
Status: In progress