search

mynodebtc / mynode

The easiest way to run Bitcoin and Lightning!
Other
626 stars 143 forks source link

Proposal for Statically Generated Documentation Website #299

Open thunderbiscuit opened 4 years ago

thunderbiscuit commented 4 years ago

I'm opening this issue to start a discussion around creating a repository and potential website for the documentation files for myNode.

tldr: check this mock/test website out

I have worked in the past with Static Site Generators to create documentation websites, and think they are powerful tools that would well fit the documentation needs for this project.

The gist of them is that you set them up to monitor a branch of a repository, and they rebuild your website every time you push to master. This makes it easy to then just keep all docs files as markdown and into a single directory. It also offers the option to completely separate the repository for the docs files from the source code repo, creating a nice separation of concerns there. Issues, PRs, and merges can happen on their own time and are not polluting the main source code git history.

I have created a mock version of a docs website by transforming the current docs into markdown files (and taking the docs files from @MitchellCash as well) and setting them up into a VuePress (an open source project that generates static documentation websites) architecture.

You can check out my repo for the website here. I have also written an article about how to kickstart a VuePress Documentation website in 8 commits if you want to go into a bit more details on how it's done. For now I just wanted to open up the discussion.

The architecture can easily be modified to adjust for more complex UI/UX if needed, but even the defaults produce an easy to use documentation website out-of-the-box. This allows contributors who might not be comfortable with frontend development to contribute to the documentation easily by simply making pull requests on the markdown files.

VuePress creates a website that you can then host on a number of platforms for free (Netlify being my preferred choice). My example website is currently hosted on GitHub Pages for free as well.

I'm not trying to push this approach necessarily, but rather I'm hoping to open the conversation on how to better cure/maintain the growing documentation for myNode. The Telegram group is obviously very active, so there is a need for good docs that we can just refer people to, and the ability to bring people in to help write good docs is an element that, in my experience, should not be underestimated.

Any thoughts there? I can take the time to explain more how VuePress websites work if people are interested.

Amiga500 commented 4 years ago

Fantastic Job!

thunderbiscuit commented 4 years ago

@abhiShandy I hear you worked on the Wiki pages... what do you think of this? We could maybe port some of those as well?

abhiShandy commented 3 years ago

This is pretty cool!

We can have two separate documentations, one for users and other for developers. The developer-doc would monitor the master branch and get auto-updated. (I don't know if Github Wiki or GitHub projects can do anything similar). The user-doc might need curation to guide a wide-spectrum of users. Perhaps @davterra might be interested in this.

davterra commented 3 years ago

Yeah, I think this is the way to go. I've contributed a decent amount of material to the Wasabi Wallet docs (docs.walletwasabi.io) and they use vuepress. Its easy and efficient.

One thing though, to do this right we need @tehelsper on board, and the docs should be a branch of the main domain, rather than a subdomain like Wasabi does it. Their way is bad for SEO, as Google treats subdomains as separate entities. I've mentioned that to them, but its on a "back burner" there for now.