Migration Guide
Milestones

[Hackathon] Docs Revamp

TeamMembers
Team@An Le, @Brian Do, @Jairo Garciga, @Minhye, @Candice Chow, @Akin
Shared LinksDesign: Docs Mockup Ideas (opens in a new tab)
Docs Reorg: “Getting Started” - Work Flow (opens in a new tab)

I. Issue:

  • Docs UI look outdated comparing to Statsig Homepage design language overall.
  • Our docs UI currently is not well organized:
    • It’s not clear between the Product Definition and Integration
    • Which one is for Feature Management, Experimentation, Analytics, Data Ingestion…
    • The integration UI/UX is quite hard to discover.
      • ConsoleAPI using RAPI which is ok Free option, not great to display each endpoint details. Its UI components tend to work like accordion which push out the other sections to different page easily.
  • It’s hard for non-technical people to contribute to due to
    • Set up Github in order to commit. They can commit directly on Github but not prefer because we prefer to have Preview before commit.
    • Even with VSCode engineers already can make mistake easily due to MDX syntax.
  • Analytics: we do have one, but not enforce on all pages.

II. Solutions:

Option 1: Improve current Docs framework

  • Description: currently we are using Docusaurus for general Docs and Rapi to generate interactive API.
  • Pros:
    • Free
    • Already using them
  • Cons:
    • Docusaurus
      • No Editor support for non-tech users - but it’s in Beta not very well implemented yet
      • Overall structure is more barebone
      • No support for API interaction integration
    • RAPI
      • Component and API rendering not very well built
  • Work to be done:
    • More work on restructuring the layout.
    • More tinkering with Rapi for better structure (may not get all the functions we want).
    • Apply analytic site wide and how to enforce for new docs.

Option 2: Move to Docs as a Service

  • Mintlify (https://mintlify.com/ (opens in a new tab))
    • Description: some big names using it
    • Pros:
      • Functionalities already supported out of the box
        • Non-github Editor for MDX docs and direct commit, preview ⇒ Quite Beta
        • Auto gen for each interactive API page + more beautiful out of the box ⇒ Ours with some work can be at Good stage.
        • Analytics - we should integrate with statsig anyway ⇒ Do we really need it?
    • Cons:
      • Pay monthly ⇒ Biggest down side?
      • Migrating all current docs ⇒ Another big task
    • Work to be done:
      • More work on migrating current docs

Conclusion v0 😆: go with Option 1

  • The advantage is not clear to justify the effort
    • To migrate
    • To pay monthly

Option 3: Rebuild from scratch with different tech stack

Final Conclusion: rebuild with Nextra

After putting in more research and seeing other companies steered away from Docusaurus to NextJS like Supabase AND I also spent 4 hours upgrading the Docusaurus with so much pain, I’m convinced that we should steer away from Docusaurus to some latest tech stack too. I found Nextra which is developed by NextJS.

  • Pros:
    • Use nextjs
      • Supposed to be much faster than Docusaurus Single Page Application.
      • Supposed better for SEO too.
    • Very customizable
      • Extendable. We can extend with much more functionalities by ourselves.
    • We own the stack
      • All our engineers already familiar with NextJS and love it.
    • We don’t have to pay monthly.
  • Cons:
    • The docs libs/plugin may not be as many as Docusaurus because it’s introduced recently. But, most of what we need I see it already covers.
    • No support for Docs Version. We are not doing it anyway, and I suppose we can implement it with a bit of effort.

III. Resources:

Good Examples

IV. Action Items

v0: Build proof of concept with Nextran

V. Wishlist (Out of scope):

v1: Feedback and Analytics

  • Install Statsig analytics
  • Rework on API page which will point to brand new page with its own Side Nav - XL
  • Feedback section on each page. Voting and feedback functionalities.

v2: Search with GPT

v3: MDX Editor

  • Create editor mode where non-technical contributors can write easily without git access. Just need to support .MD first later on can expand to .MDX
Code Playground