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:
-
Should we spin up a UI (such as with gitbook or docusaurus) for our docs?
-
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.