Raspiblitz: Restructuring of documentation

[0xjacobb]

Hi there

I've set up a raspiblitz the first time during the last days. this project is great, with a lot of information. But, I found it hard to separat all the information at the beginning. Therefore, I had the idea to restructure the documentation a little bit. I am fresh to the project and apologize if you have already discussed this idea or you have some clear arguments against it.

• README.md: Short, clear installation instructions

• Detailed Documentation: Separated in a file like "DOCUMENTATION.md"

• Release Notes: Separated in a file like "RELEASE_NOTES.md"

cheers.

[openoms]

Agree that we could improve on the presentation.
On TG there was also a discussion of creating a github page/ gitbook/ just the docs or similar for listing the chapters, FAQ-s etc.

[0xjacobb]

Agree that we could improve on the presentation.
On TG there was also a discussion of creating a github page/ gitbook/ just the docs or similar for listing the chapters, FAQ-s etc.

So, are there any accounts available for github page/gitbook or similar? Or is anyone in charge of this?

[openoms]

I am experimenting with how it would be best to host some better organised documentation.
We will likely need to link to some static documentation pages from the GUI. Hosting those on GitHub allows us to safely update and track the changes.
All three of electrs, btc-rpc-explorer and btcpayserver are quite important for a full node user overall, but will need some explanation pages outside of the scope of the installation dialogues.

The options I was thinking of:

• GitHub pages: this could be activated by @rootzoll on the current repo to be served from the /docs library, maybe using the Just the docs theme as in the examples.
  Links could look like these (only experimental for now):
  https://openoms.github.io/raspiblitz/FAQ.html
  https://openoms.github.io/bitcoin-tutorials/electrs/

For a shorter link we could use GitHub pages with a GitHub organisation (hosting only the docs) :
https://raspiblitz.github.io/FAQ.html

• Gitbook.io: with a free registration it looks like this:
  https://openoms.gitbook.io/raspiblitz/
  https://openoms.gitbook.io/lightning-node-management/

  (need to pay to use it for as an organisation)

[0xjacobb]

I made a Gitbook as well in the past, was very easy. Yours looking good.

[thunderbiscuit]

Hey there! Anyone working on this? I've been using VuePress static documentation websites for a while now and they are really easy to set up and work/look great. VuePress is basically an open source project Static Site Generator that focuses on documentation websites.

It's very similar to GitBook, but you're in complete control of the UI/UX. Easy to host for free on GitHub pages or Netlify. You basically set them up, and then feed them markdown pages. Easy to incorporate contributions because people can just make PRs on the markdown (similar to GitBooks in that sense!).

I wrote a blog post that basically outlines the first 8 commits you need to get going. You can check out the resulting template website here.

Anyway just offering to help set one up if there is interest. Raspiblitz already has a lot of markdown documentation files, so it's a perfect candidate for this kind of thing.

For an example of how flexible they can be, you can check out Wasabi's documentation website. I was part of the group that set it up, and we considered GitBook, VuePress, Docsify, and Gatsby/Docz. All great projects, but ultimately VuePress strikes a great balance between ease of use and power.

[thunderbiscuit]

The way I see it, you can keep track of docs in two ways, both with advantages and tradeoffs, and both apply whatever your choice of architecture for the docs (GitBook, VuePress, Gatsby):

1. You keep them in your source code repository under a /docs/ directory. This has the advantage of keeping everything together, at the cost of polluting the source code git history with a lot of small markdown changes to docs.
2. You keep the docs in a dedicated repository. This makes for a separation of concerns, where the docs are not developed with the source code per se.

I think keeping the repos separate this is the better approach for projects of size. It allows for frontend and documentation work to not pollute the source code repo, and keeps the issues and PRs easy to parse on both sides. At the same time, if all you need is a small website with 10 markdown pages or less, then keeping them in your repo might be a cleaner way to do it, just so as to not have to keep track of two repositories. Of course you can also have different people with commit access to the different repos if you split them, removing a bit of the pressure of review on the source code developers.

[thunderbiscuit]

Here is what the site looks like when I simply port the markdown and rearrange a bit (source code here). I use a starter template I keep here that I fork and simply add the files. I haven't put much work into it at all so it's very rough, but still, it gives an idea of what these docs websites can look like.

Happy to pass on the ownership of the repo if there is interest! (Or feel free to just fork and deploy whatever you like in there if you decide it's a good option for this project). Happy to explain more of the internals of VuePress if there is interest for this particular option.

You can easily fire up the server for local development if you want to test for yourself as well. You'll need NodeJS and Yarn, then:

git clone https://github.com/thunderBiscuit/raspiblitz-docs-example
yarn install
vuepress dev docs # will run the website at http://localhost:8080/raspiblitz-docs-example/

[INSG2020]

For an example of how flexible they can be, you can check out Wasabi's documentation website. I was part of the group that set it up, and we considered GitBook, VuePress, Docsify, and Gatsby/Docz. All great projects, but ultimately VuePress strikes a great balance between ease of use and power.

We also think that restructuring the documentation would be a huge win!
Had the same feedback from beginners who found the readme file overloaded with information in one file.

https://docs.wasabiwallet.io/using-wasabi/ELI5.html#introduction
The menu of the Wasabi documentation, expanding automatically up to 3 layers is very structured.
The same for the FAQs.