Skip to content
This repository has been archived by the owner on Jun 15, 2021. It is now read-only.

Migrate Bisq docs to more flexible platform #131

Open
m52go opened this issue Apr 25, 2019 · 1 comment
Open

Migrate Bisq docs to more flexible platform #131

m52go opened this issue Apr 25, 2019 · 1 comment
Assignees

Comments

@m52go
Copy link
Contributor

m52go commented Apr 25, 2019

AsciiDoc is a pleasure to write in, but Asciidoctor is drastically limited in format and features—it's just a big wall of text, no matter what. Most notably, there is no way to provide search, and no way to adjust the UI without tons of work.

Instead of wrestling with this limited framework, it makes more sense to me to consider migrating to another framework that's more flexible and feature-rich from the start.

I don't have any specific ideas at the moment, and I don't think this is an urgent priority, but as we have more docs over the next few months (roles docs in particular), the front page will start to get unwieldy.

Therefore I'm creating this issue as a starting point for suggestions and consideration, so that more concrete action can be taken in the next 5-7 months (probably after making a more specific proposal in bisq-network/proposals once details are known).

cc #128

@m52go m52go changed the title Migrate Bisq docs to more feature-rich platform Migrate Bisq docs to more flexible platform Apr 25, 2019
@m52go
Copy link
Contributor Author

m52go commented Sep 11, 2019

I'm experimenting with integrating docs into the website through a Jekyll plugin called jekyll-asciidoc.

Benefits:

  • gain ability to implement features like search, translations, and better navigation
  • can continue writing in AsciiDoc
  • no need to learn and maintain a new framework (VuePress, Antara, etc)
  • we already maintain a Jekyll site
  • harness the traffic and SEO of the main Bisq site

My initial integration of content went well. The following remains:

  • implementing search (lunr.js looks promising; it accomplishes search by generating an index at build time that's sent to clients and queried right in the browser)
  • determining a navigation layout that combines site navigation with docs navigation that's not unwieldy (have ideas and mockups)
  • having a plan for translations (should be able to use the existing translations mechanism combined with asciidoc attributes)

More importantly, we need to decide if this integration is a good idea from an organizational standpoint, since the website and docs maintainers have historically been different roles, and this integration would effectively put both repositories under the control of one role.

I want to get other docs done before spending more time on this, so I make this update in search of feedback, with the intention of revisiting it in a month or so to implement.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant