Migration of existing docs to official GitHub docs

General
1

Content Migration Proposal

Mainly for @abo, but keeping it public since others may want to join the conversation or directly help.

I have a large amount of content in two sources that I’d like to partially migrate to the official docs:

1. Node Guide

This guide contains many contents that include my custom scripts and auto-installer, which may not be suitable for the official docs. However, there is still some valuable material to use. The language is generally “noob-proof” and not very technical, though I’m unsure if this is acceptable for the official docs.

2. Wiki

This resource contains various articles. Some are directly sourced from the Quilibrium Blog or this forum. In some cases, I rewrote the contents to make them more digestible. Could they be included in the “Learn” section of the new docs (docs/docs/learn at main · QuilibriumNetwork/docs · GitHub)? I’m uncertain because currently that section seems reserved for technical information only.

Proposal

Let’s use this conversation to decide what is worth migrating and how/where, so I can avoid opening PRs that are not aligned with your plan.

4 Likes
2

For the current “Docs > Run” (Quick Start | Quilibrium Docs), I would add:

  1. Setup the gRPC calls:
    Set up the gRPC calls | Quilibrium.one

  2. Running with Docker (guide by @0xOzgur)
    Running With Docker | Quilibrium Space Documentation

  3. Installing the qclient on Windows via WSL:
    Installing the node and the qclient on Windows WSL | Quilibrium.one
    This one needs to be carefully reviewed as I have only tested the workflow once, some time ago

  4. CLI commands for the qclient (QUIL token management):
    CLI Commands in Quilibrium 2.0 - for token transfers | Quilibrium.one

  5. Backing up your node:
    A more detailed guide compared to the small current paragraph.
    Some resources (Backup your node | Quilibrium.one)

  6. Running a node cluster:
    Running a node cluster | Quilibrium.one

  7. Managing your system resources:
    Managing your system resources | Quilibrium.one

… next I will propose which WIKI articles to migrate from here Links & Info | Quilibrium.one

UPDATE:
since the “learn” section seems to be dedicated to technical material, maybe makes sense to create a “WIKI” section where to publish articles from the Q blog and my Wiki?

2 Likes
3

Hi @LaMat,

Thanks so much for writing this up and for your work on Quilibrium.one!

In general, my thinking on the official docs for node running is that it

  1. The official docs should have a quick start to get a node up and running easily on the most popular platform. I think the current quick start + Linux configuration page achieves this. Adding more platform-specific guides is risky if we don’t use those platforms.
  2. The official docs should be the single source of truth for all things where things can go wrong (access control for the node, privacy considerations, key management, what to backup).
  3. The official docs should serve as a reference level documentation for all configuration options, RPC methods and CLI commands.

I went through the pages that you proposed moving over with this in mind and my feedback would be this:

  1. Setup the gRPC calls:
    Set up the gRPC calls | Quilibrium.one

I think how to edit the config file is out of scope, but it’d be great to have example values for listenGrpcMultiaddr and listenRESTMultiaddr config options and clarification about access control.

  1. Running with Docker (guide by @0xOzgur)
    Running With Docker | Quilibrium Space Documentation

Since Quilibrium switched to binary releases, running in Docker is pretty straight-forward, and the contents of this page looks more Docker focused than Quilibrium-specific, so I’d say this is out of scope. It’d be nice to have example commands for grpcurl (without Docker) though.

Installing the qclient on Windows via WSL:
Installing the node and the qclient on Windows WSL | Quilibrium.one

It looks like there are no Quilibrium-specific things needed to get qclient working on WSL, so I’d skip this.

CLI commands for the qclient (QUIL token management):
CLI Commands in Quilibrium 2.0 - for token transfers | Quilibrium.one

This would be awesome to have under a CLI Client page in Node Running.

Backing up your node:
A more detailed guide compared to the small current paragraph.
Some resources (Backup your node | Quilibrium.one )

In my reading this page is centered around executing a script from a third party repo. As you noted, we cannot include such a script in the official documentation for security reasons.

In any case, I’m not sure if we should have detailed backup guides for specific tools in the official docs. These are a lot of effort to maintain and it’s not different than backing up any other database on a server for which there are many guides on the internet. Plus another consideration is if everybody is using the same backup solution and it has a problem, that’s not good for the network.

Maybe what we could mention in the docs is that in addition to simply making copies as backups, incremental backup solutions with snapshots like Restic work well to back up the database.

Running a node cluster:
Running a node cluster | Quilibrium.one

This would be nice to have more info on, but I’m not too familiar with running a node in a cluster. @Tyga added a partial Running a node in a cluster section in the last release. Maybe you could coordinate with him?

Managing your system resources:
Managing your system resources | Quilibrium.one

I think adding CPU limits is only a concern until 2.0, so we probably don’t need this going forward. Should revisit after 2.0 release if it’s still a problem.

since the “learn” section seems to be dedicated to technical material, maybe makes sense to create a “WIKI” section where to publish articles from the Q blog and my Wiki?

Yeah the Learn section is quite technical and it was all done by Cassie for the original website. Regarding the Wiki that you compiled, I think that’s great to have, but it’s out of scope for the docs as it’s more like a compilation of different sources in a more easily digestible way.

Thanks again!

2 Likes
4

I do not think that it’s a bad idea to have a Guides section to more advanced features. People can write and maintain them themselves and of they are good enough they can be accepted.

Or Cassie can yay or nay guide topics that will be published and submissions towards those topics will be considered

They may be a use for 3rd party guides as there are many different flavors and “right” ways to do things. I’m finding that many of the ways I’m doing things as I learn to not actually be best practices… But they still work. I certainly don’t know how much better it would be to have done it as intended or professionally, but until there is a system engineer or two who publishes their work or gives feedback, we are left to our own devices, pun intended.

To summarize, publishing guides that work, while not perfect are a large step forward for many people.

A lot of these are intermediate steps until there are official tools that abstract all of this away.

5

Do you have a specific example in mind? I don’t think we disagree

6

Thank you for taking the time to review everything!

I largely agree with your points and understand that official documentation must be kept concise. However, I disagree regarding the Wiki. In my opinion, having an official Wiki would be beneficial, as currently, the content is scattered between the forum and the blog, often in a format that’s not easily digestible.

Ideally, the Wiki should cover every aspect of Quilibrium. Each article could have a condensed, easy-to-understand explanation, as well as a more comprehensive version that delves into all technical aspects. Additionally, a complete list of FAQs would be useful, similar to this one: https://docs.quilibrium.com/start/wiki/faq

I recognize that maintaining an official Wiki would be challenging, though.

Therefore, for the time being, it might be best if I continue to maintain my unofficial Wiki, along with the unofficial node guide and scripts.

If I’m unable to maintain these resources in the future, I’ll make an announcement.

2 Likes
7

I noticed you’ve already added a link in the documentation to @Tyga’s forum guide. I believe this is sufficient, as users can also access the conversation within the forum, which contains many useful tips.

1 Like
8

Yeah that was added by @Tyga and he indicated that he’d migrate the whole guide later which is I think a good idea.

9

In my opinion, having an official Wiki would be beneficial, as currently, the content is scattered between the forum and the blog, often in a format that’s not easily digestible.

Yeah it’d be good to have a single source of truth in a condensed format for some additional topics not currently in the docs, but I’m a little hesitant about adding a Wiki for two reasons:

  1. In my reading the Wiki that you have covers questions a blockchain user may have, contains info for builders + the history and the roadmap. We already have a builders section in the docs, but covering questions blockchain users have would be a good addition to the docs site, and I can see the history as a Wiki entry, but beyond that I’m not sure what would go into the wiki.

  2. Let’s say our goal is to create a reference for blockchain users’ questions. I think a Wiki is not the best format for this, because that’d break up topics into standalone articles that are not targeted at a specific demographic and it’s not clear where to start.

So what I’d propose is to add a “Quilibrium for Blockchain Users” subsection to the Learn section that contains a short overview and topics like how wallets work, how transaction fees are paid, how decentralized it is, how Q compares to other networks and how Q prevents illicit activities.

10

I agree, let’s do that and I’ll migrate some articles.
I would also put there the current FAQs?

I think that is a pretty important section to have.

1 Like
11

Awesome thanks! Yeah it’d be good to migrate the FAQs as well. We could add a FAQ page under “Quilibrium for Blockchain Users” with questions that logically fit there, for example token and DEX related questions and possibly the status of Q Inc. Edit: on a second thought I’d omit the status of Q Inc. from the FAQ that has questions about the token to avoid giving the impression by accident that the token is some sort of fundraising instrument for Q Inc which it is very clearly not.

Questions under “Node running FAQ” I’d add as a FAQ page under the “Run node” section in the docs. Questions about roadmap and marketing we could omit and possibly questions about the 2.0 launch as well as they’ll likely be outdated by the time the site is updated.

12

I added the FAQ for blockchain users.
I have reviewed the FAQ for Node runners but I think we can omit all of them, as most of them apply to the 2.0 launch or the answers are already in the existing docs and easy to find.

2 Likes
13

@abo a redirect is needed
from https://quilibrium.com/docs
to https://docs.quilibrium.com/
as the old link still lives in many places.

Thanks

14

Thanks, I’ve let Cassie know, as I don’t have access to quilibrium.com

15

No problem. I am waiting for your feedback before migrating more articles in the “Quilibrium for Blockchain Users” section.

1 Like