Should clrfund docs have their own UI and/or repo?

clrfund’s technical documentation is pretty great. However, their current location may limit their usefulness to the full range of clrfund users and contributors.

With that in mind, I’d like to raise two questions:

  1. Should we spin up a UI (such as with gitbook or docusaurus) for our docs?

  2. Does the above question nudge us towards sticking with a monorepo (rather than splitting into separate front-end and contracts repos)?

1. Docs UI?

While the existing docs are really helpful, their accessibility to non-developers is limited, and, relatedly, they focus predominantly on technical/development topics.

To the degree that the clrfund community would value a) making docs more accessible to all users and contributors, and b) expanding content to include other topics such as user docs / FAQs, clrfund-deployer docs, etc., we should consider adding a UI for our docs via something like Gitbook or Docusaurus.

One advantage of our current approach is that docs are more tightly coupled with code, which makes it more likely that PRs will include both code changes as well as the necessary docs changes. Losing that connection could result in worse documentation. This consideration brings us to our next question.

2. To Mono or not to Mono?

That has been the question over the past few weeks.

In my view, the benefits of a tighter relationship between code and docs is a good argument to maintain our monorepo structure rather than splitting into separate repos. A monorepo with a docs directory would allow the docs to cover all aspects of clrfund (core contracts, subgraph, front end, deployer, use cases, user FAQs, etc.) and be modified in conjunction with changes to those aspects.

However, if supporting a docs UI would require a separate docs repo, then those benefits couldn’t be realized anyways, in which case the case for a monorepo becomes weaker.

Best of both worlds?

It’s possible we might be able to achieve both a dedicated docs UI and keep a monorepo structure if a Gitbook and/or Docusaurus app can be served from a directory within a monorepo. From what I can tell, this may work with Docusaurus and Githbub pages, since the latter can be configured to use a specific folder as a publishing source.


What do you think? Please weigh in here.


Thanks for raising this idea @spengrah!

My two Gwei - I think investing in a docs UI is a worthy endeavor. The current set up works great from a dev workflow perspective but is clearly not optimized to new/non-technical users.

I haven’t done any research on the how but I think achieving the “best of both worlds” like you mentioned would be ideal, where we can spin up a doc frontend that points to a specific folder (e.g. & auto-deploys on merges. One open question is if that muddies up our project dependencies at all (would /docs/ directory have its own package.json?).

If the monorepo approach isn’t possible, I’d also be perfectly fine contributing to a standalone docs repo. The developer flow wouldn’t be as ideal (2 PRs for certain changes) but I think the wins it could create in terms of user education & lowering barriers for new folks to become contributors would be worth the DX cost.


Sorry for the slow reply here guys.

Yes, I think think issue of where to host the docs has pushed me back in the direction of wanting to keep everything in the monorepo. That would include moving things like the deployer and the subgraph into the mono repo as well.

I went ahead and set up a feature-vuepress branch on the mono repo.

@spengrah, I decided to go with vue-press just to keep the frontend framework consistent between the app and the docs. It is not quite as full-featured as Docusaurus, but it does everything that we need and is quite easy to use.

1 Like

Cool, makes sense to me, and its not a high risk decision anyways since I don’t think it would be very costly to switch if for some reason vuepress doesn’t work out.