Publish Bisq Network documentation to https://docs.bisq.network #36
Conversation
See README.md for details.
This is primarily to facilitate the use of Gradle`s --continuous flag without triggering infinite builds due to the contents of the 'build' directory changing.
Inspired by the way the Spring Framework reference docs do this.
I put everything in src to make it possible to do Gradle continuous builds, but in the end this isn't worth it. The actual asciidoctor build is too slow, and even with LiveReload in the mix, the turnaround time wasn't sufficient. In the end it's better to go with instantaneous rendering in the browser with the Asciidoctorjs Chrome plugin, and do full `gradle asciidoctor` runs on an as-needed basis. As a side benefit, the existing 'dao' and 'exchange' docs "just work" once again, without needing to be moved. The idea for now is to keep everything as flat as possible, right in the root directory, but no harm keeping these docs where they are for a bit while writing everything else.
This avoids png files being copied to infinite depth and causing Gradle to blow up on filenames that are too long.
And add placeholder getting started doc.
This change causes NOTE, TIP, and other admonitions to be rendered with pretty icons instead of plain text. See: - https://asciidoctor.org/docs/user-manual/#admonition - https://asciidoctor.org/docs/user-manual/#admonition-icons
There was a problem hiding this comment.
Great initiative!
There is a deal link:
https://docs.bisq.network/account-age-witness.html
Beside that ACK
|
ACK Big thumbs up for kicking this off! I like the style and especially if we are using style elements like in https://docs.bisq.network/exchange/howto/list-asset.html it is really enjoyable to read documentation. Hopefully this doesn't speed up the ...coin PR's a lot 😉 |
And remove BIP-style header; we'll move away from this approach, as we're not really ready or in need of this level of formality.
|
Yes if we get too many PRs for coins we can consider a BSQ fee in future. They are used to pay to get listed. Usually in the 100k area... |
|
Thanks for the reviews, both. @ManfredKarrer, the payment account age doc is live now, thanks for catching that. See commit 2d497b5 in particular. I'm going to remove the doc from the proposals repository as well. I want to move toward having proposals be an issues-mostly (possibly issues-only) repository going forward, more about proposing changes to how we work together, etc, than about formal BIP-style proposals. Where written specs are helpful (like they were in the case of the account age witness feature), we can just add a doc to the docs repository like I've done just now in the commits above. So proposals become distinct from specifications or "RFC" style docs. In any case, I'll merge this PR shortly. |
See bisq-network/bisq-docs#36, in particular commits bisq-network/bisq-docs@f64915b and bisq-network/bisq-docs@2d497b5.
See bisq-network/bisq-docs#36, in particular commits bisq-network/bisq-docs@f64915b and bisq-network/bisq-docs@2d497b5.
Publish Bisq Network documentation to https://docs.bisq.network
Rationale: this, like other bisq-* code repositories is a repository that we want and expect many people to fork and submit PRs from. Thus, it's good to have it qualified as bisq-docs, such that people don't end up cloning an unqualified 'docs' repository that ends up in forked repositories being named alice/docs, bob/docs, etc. See bisq-network/bisq-docs#36
Currently we have a pretty scattered and primitive collection of documentation, some in the bisq-desktop wiki, some in this repository, some still in GDocs.
What's needed is a single, well-organized documentation portal for all things Bisq, where we can publish user-facing docs like an official "Getting Started Guide", as well as contributor-facing and developer-facing docs.
These changes are the first steps toward that documentation portal, including:
index.adoc, which categorizes and lists our most important existing documentsintro.adoc, which is new and provides a brief introduction to Bisqgetting-started.adoc, which is still a placeholder, but will become the go-to place to learn how to install, configure, fund and trade with Bisq.Note that while both user docs and contributor docs are important, my main motivation in doing this work now is to give us a solid foundation to start writing more contributor- and developer-focused documentation. If we're going to successfully decentralize the human aspects of Bisq and achieve the Phase Zero exit criteria, we need to get everything out of our heads and into writing, so that new contributors can get onboarded as quickly as possible, and "self-serve" as much as possible.
As described in the README, everything is hosted via Netlify at https://docs.bisq.network (just like the https://bisq.network website is), and deployment is push-to-publish via GitHub. Currently, the live site is published from this PR branch, but after this PR is merged, I'll change publication to be based on the
masterbranch of this repository.I encourage all interested @bisq-network/contributors to review this PR (even after it's merged) to understand how this infrastructure works, and of course to provide any feedback.