Restructuring of documentation #3939
Replies: 8 comments
-
Agree that we could improve on the presentation. |
Beta Was this translation helpful? Give feedback.
-
So, are there any accounts available for github page/gitbook or similar? Or is anyone in charge of this? |
Beta Was this translation helpful? Give feedback.
-
I am experimenting with how it would be best to host some better organised documentation. The options I was thinking of:
|
Beta Was this translation helpful? Give feedback.
-
I made a Gitbook as well in the past, was very easy. Yours looking good. |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
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):
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. |
Beta Was this translation helpful? Give feedback.
-
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/ |
Beta Was this translation helpful? Give feedback.
-
We also think that restructuring the documentation would be a huge win! https://docs.wasabiwallet.io/using-wasabi/ELI5.html#introduction |
Beta Was this translation helpful? Give feedback.
-
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.
Beta Was this translation helpful? Give feedback.
All reactions