Document Portal

[bedeho]

Background

The JIP repository is the primary destination for collaborating on and publishing JIP documents, however being able to conveniently consume the information in these documents is a distinct purpose, and the JIP Document Portal attempts to serve this objective. It is a collection of webpages which can provide a web experience, powered by the repository and the chain (indexing service), that is very convenient for consumption and discovery of JIP documents. Here are some examples of benefits

1. HTML version of all documents with generated TOCs.
2. An index HTML page of all JIPs with key information derives from documents, e.g. stage and owner(s), as well as most recent values for Joystream Process Parameters set by council.
3. Full links to configurable websites for resolving on-chain links, e.g. some Pioneer or Atlas instances.
4. Rendering on-chain resources with rich presentation, such as members with full handles and avatars. (would require being online during generation step)
5. Free-text search and browsing functionality across proposals documents.
6. Reverse lookup based on members, JIPs, and other identifiers.

In the future perhaps this can be incorporated into Pioneer, but to avoid that extra complexity it's better to keep it separate.

Proposal

Implement a first version of the portal which can present the desired experience to users by scraping the repo and a QN. It's important that the experience is not too slow, so perhaps preloading all JIPs an other relevant content during a loading stage perhaps would increase usability.

Also, defining a more narrower MVP scope than all points above, for example 1+2+3.

┆Issue is synchronized with this Asana task by Unito

[DzhideX]

For the MVP (points 1,2 and 3), I propose the following solution:

We can use NextJS as the React framework to build the site. The reasons for Next are:

• built by Vercel so it works great considering we already use their services (deploying sites, ci/cd integration) for other sites across the organization
• fine-grained choosing of rendering paradigms (SSG, SSR) depending on the route
• many performance optimizations (images, link prefetching, and more)
• allows for the creation of API routes (so that we don't need a separate solution for a server in case that comes up)
• simple to use and get the hang of if others wish to contribute later down the line

Assuming we go with Next, we can use Static Site Generation (SSG) to read and parse the markdown files while building the site. This would allow us to just render static files and no extra fetching would need to be done by the user which should make the site very snappy/fast (at least when it comes down to the markdown files themselves, fetching from QN might be unavoidable). I believe that with this and the API route functionality we should also be able to implement 5 and 6 in a clean way when we get there.

As for the "place" of the implementation, the idea is to add a folder in the root of the repo (e.g., /portal or /site) and implement this within there.

Question:

• What should we do about the styling? Do I wait for designs from someone or do I maybe try to take my own stab at it? (disclaimer: I'm not the best designer..)

Let me know what you think and if you have any questions @bedeho!

[bedeho]

Sounds like a plan, nice breakdown!

maybe try to take my own stab at it?

Yep, just go for it ;)

[DzhideX]

Okay, finally have something to show here :) Since we don't have anything set up on this repo currently I went ahead and set up vercel on my fork. Here is the preview from the latest work that I've done (branch: implement-jip-portal): https://jip.vercel.app/

The functionality in it aims to implement the first 3 points outlined in this issue (except this part "as well as most recent values for Joystream Process Parameters set by council" as I believe it's not quite yet relevant ~ let me know if I'm wrong though!). I've also gone with a very barebones approach to styling so as not to waste too much time as I believe more input will be needed from you on that front anyway. Let me know what you think and if there's anything you'd like to add/change/remove!

Note: For the content, I used the draft of jip-1 from the open PR in the repo. I also went ahead and expanded the "Joystream On-Chain Links" section with the integrated on-chain link functionality and also added some placeholder "text" to the changelog table at the end.