Bisq Docs Maintainer

[cbeams]

This role is responsible for maintaining the bisq-network/bisq-docs repository, which backs the https://docs.bisq.network site.

---

Docs: none, other than the above Team: @bisq-network/docs-maintainers Primary owner: @m52go

[cbeams]

2017.12 report

Not much to report this month, save for the fact that @Francewhoa has begun to get involved with the documentation effort (welcome, @Francewhoa!) and may do additional work in the future on guides like bisq-network/docs#21. Otherwise, I made minor updates to existing docs, and added a couple bounty issues like the one linked above.

Note that the Slack chats with @Francewhoa starting here are worth a read for anyone interested, as they lay out a lot of the thinking behind the docs repository and our overall approach here.

/cc bisq-network/compensation#26

[cbeams]

2018.01 report

No major work done around docs, other than keeping existing docs up to date. We still have outstanding bounties for how-to guides; no takers as yet.

/cc bisq-network/compensation#35

[cbeams]

2018.02 report

Nothing to report on docs.

Help wanted! Someone who can fully own and take initiative with Bisq's docs could add a lot of value to the network.

The ideal docs maintainer would have:

• Strong technical writing skill
• High editorial standards
• Git + GitHub expertise
• Markdown skill, @asciidoctor love
• Experience working in open source
• Ability to attract other similar contributors

/cc bisq-network/compensation#40

[cbeams]

I just tweeted a link to the above at https://twitter.com/bisq_network/status/968998436463955968. If you're here because of that and think this is something you'd be interested in, read https://bisq.network/phase-zero and come talk to us in #docs at https://bisq.network/slack-invite.

[cbeams]

2018.03 report

There was very little activity around docs this month, other than the usual maintenance of existing documentation. One thing I've been thinking about now that we've split up the old bisq-network/exchange repository into bisq-common, bisq-core, bisq-p2p, bisq-desktop, etc is whether we want to continue with a dedicated docs repository like we have now, or possibly to move (back) to a docs directory within each repository. Certain docs like the phase-zero doc, and our various whitepapers do not belong in any one component repository, so there should probably continue to be a top-level 'docs' or 'whitepapers' repository in any case, but other docs, like how to list an asset could probably live directly in the bisq-core repository. We may also want to move toward a "user manual"-style document (which probably would have its own repository, like we have with 'docs' now), where the idea is to collect and organize everything into a single resource. Perhaps we want to do a 'user manual', a 'contributor manual', etc., to address our different major audiences. I don't know—just thinking out loud here.

/cc bisq-network/compensation#57

[dsbeasley]

Also interested in this role!

[cbeams]

@dsbeasley, thanks for your interest. The best thing to do for a start is to contribute to docs, i.e. submit your own pull requests and review those of others. I know you're already in Slack—let's chat there in the #docs about work you might be interested in doing.

[cbeams]

2018.04 report

Big changes to docs this month!

• @cbeams created new docs.bisq.network site and published existing documentation there
  • https://github.com/bisq-network/bisq-docs/pull/36
• @cbeams produced Intro to Bisq doc
• @cbeams produced New Contributor Checklist doc
  • https://github.com/bisq-network/bisq-docs/pull/39
• @cbeams produced Proposals doc
  • https://github.com/bisq-network/bisq-docs/pull/40

These changes were promoted via Twitter to good effect.

Also, @m52go has gotten involved, and is in progress producting a Getting Started with Bisq document at https://github.com/bisq-network/bisq-docs/issues/37.

In general, all @bisq-network/contributors are encouraged to get familiar with the new docs site, and to begin thinking about it as the place to document all the most important things about Bisq.

When we talk about what it means to deliver a contribution, we should always be asking ourselves the question, what needs to change or get added to the documentation such that users can discover and understand my contribution?

The docs site is primitive today. You can think of it as something like "a wiki that wants to become a full-fledged manual". For right now, everything is flat. If there is something you want or need to document, come chat about it in #bisq-docs, and then put together a pull request for it, just like any other under.

From a visual design perspective, the new docs site will be one of the things we want to get aligned with the new design vision coming together with @pedromvpg, @diogorsergio and others. This should be relatively low-hanging fruit, is its' mostly about adapting the existing default Asciidoctor CSS and fonts to align with the new design. This is something I've helped do in previous teams and I can point to that work for a reference point on how to do it.

Questions and ideas welcome about this new infrastructure. Let's chat in #bisq-docs in slack.

/cc bisq-network/compensation#68

[cbeams]

2018.05 report

The focus on building out https://docs.bisq.network continued this month.

• @cbeams outlined, @m52go wrote and @cbeams edited the new Getting Started with Bisq and Secure Your Wallet guides, per bisq-network/bisq-docs#37, bisq-network/bisq-docs#45 and bisq-network/bisq-docs#58.
• @cbeams is in progress building out a table of contents for the new docs site at bisq-network/bisq-docs#60.
• @blabno is at work on a getting started guide for the Bisq HTTP API at bisq-network/bisq-docs#54.
• A new @bisq-network/docs-contributors team has been created. Let me know if you want to be added to it. See https://github.com/bisq-network/bisq-docs/pull/59#issue-191056572 for more details.

/cc bisq-network/compensation#74

[cbeams]

2018.06 report

A lot of work in progress this month, but little delivered.

Delivered

@cbeams:

• Expand docs index into a comprehensive table of contents (Part I: User Docs): https://github.com/bisq-network/bisq-docs/pull/60

In progress

@cbeams:

• [WIP] Produce 'Glossary' doc: https://github.com/bisq-network/bisq-docs/pull/76
• [WIP] Produce 'Roles' doc: https://github.com/bisq-network/bisq-docs/pull/46
• [WIP] Produce 'Payment Methods' doc: https://github.com/bisq-network/bisq-docs/pull/73
• [WIP] Produce 'GitHub' doc: https://github.com/bisq-network/bisq-docs/pull/64
• [WIP] Produce 'Compensation' doc: https://github.com/bisq-network/bisq-docs/pull/62
• [WIP] Produce 'Voting' doc: https://github.com/bisq-network/bisq-docs/pull/65
• [WIP] Produce 'Support' doc: https://github.com/bisq-network/bisq-docs/pull/66

@blabno, @cbeams, @m52go:

• Produce Bisq HTTP API Getting Started guide: https://github.com/bisq-network/bisq-docs/pull/54
  • Reviewing @blabno's original work
  • Part of larger effort to deliver Bisq HTTP API

/cc bisq-network/compensation#89

[cbeams]

2018.07 report

• @cbeams wrote the new Roles doc in https://github.com/bisq-network/bisq-docs/pull/46, @m52go reviewed it, and it's now published / delivered.
• @cbeams enabled analytics on the docs site and then a few days later added a link from the https://bisq.network/downloads to https://docs.bisq.network/getting-started.html. This seems to have boosted traffic to the page quite a bit, as it's now the most visited page after the index itself with more than 1,000 views and a pretty good average time on page of 4 minutes. (FYI @m52go)

I'll include a screenshot like the one below of the monthly analytics overview in these reports from here out if others find it valuable.

BSQ requested: 100

/cc bisq-network/compensation#101

[cbeams]

2018.08 report

Several small updates were made to docs by @m52go in preparation for the v0.8.0 release, and @ManfredKarrer was added as a secondary maintainer so that he could merge PRs when I'm unable to.

This month's analytics:

BSQ Requested: 50

/cc bisq-network/compensation#114

[cbeams]

2018.09 report

Several smaller changes were made to docs over the month, the most significant of which was @joachimneumann's addition of architectural details to the bisq-mobile doc in https://github.com/bisq-network/bisq-docs/pull/85.

This month's analytics follow, this time around comparing the current month to the previous to make it easier to see the delta. Looks like upstats all around—particularly around the Market Kick-Start day.

BSQ requested: 50

/cc bisq-network/compensation#139

[cbeams]

2018.10 report

No major changes to the docs site this month.

It's interesting to see this month's analytics numbers decrease, given all the extra trading we saw. I guess our Monero users don't need documentation ;)

BSQ requested: 25

/cc bisq-network/compensation#160

[cbeams]

2018.11 report

@m52go submitted several PRs this month, and is generally planning to contribute further in the near future.

There was a slight decrease across most pages this month as compared to last:

BSQ requested: 25

/cc bisq-network/compensation#179

[cbeams]

Per https://github.com/bisq-network/roles/issues/1#issuecomment-444857417, I've handed off the primary docs maintainer role to @m52go. He'll merge incoming PRs, handle monthly updates, etc from here out.

[m52go]

2018.12 Report

MaxHillebrand submitted a PR, which I reviewed and we mutually agreed I'd take it over in January. Otherwise it was a quiet month for docs.

/cc bisq-network/compensation#199

[m52go]

2019.01 Report

Significant additions included 2 DAO docs and a doc on the data directory (backup and recovery).

@alexej996 and @HarryMacfinned you might find that last one helpful for support: https://docs.bisq.network/backup-recovery.html

Metrics were pretty good, mainly because of what looks like a GRIN spike:

/cc https://github.com/bisq-network/compensation/issues/219

[m52go]

2019.02 Report

Significant changes included a doc for making compensation requests, a doc for listing DAO resources, and a slightly updated interface for the front page to help people quickly find main docs.

Began a new initiative to make the site faster (as measured by Google's Search Console). Speed is already pretty good, but refinements in progress will make it even better.

Metrics were down a bit, because of what looks to be the GRIN spike from last month:

/cc https://github.com/bisq-network/compensation/issues/234

[m52go]

2019.03 Report

A minor addition was merged to docs this month: instructions for past contributors to specify a new mainnet address.

Also implemented some speed improvements to boost page loading speed. Desktop is now a perfect 100 and mobile is 94. Cannot get mobile to 100 without some serious work on the way AsciiDoc itself works (i.e., deferring font-awesome asset loading, which cannot be easily changed). See scores here.

A relatively major update to docs is in the works: a new section for the DAO that includes a User Reference for various practical details of DAO workings for users.

Here's the traffic snapshot. I think the jump in visits in late March is probably from past contributors looking at the Compensation page, as that's about the time they were contacted, and that's the page they were directed to.

/cc https://github.com/bisq-network/compensation/issues/257

[m52go]

2019.04 Report

There was a good chunk of work done on docs in April, especially in the days before and after the DAO launch.

Most significant updates/additions:

• DAO user reference
• new DAO tech spec
• DAO user guide for contributors
• DAO user guide for traders

Here's the traffic snapshot.

/cc https://github.com/bisq-network/compensation/issues/277

[m52go]

2019.05 Report

Quiet month for docs...much work was merged last month. This month the compensation doc was updated to reflect new conventions now that the DAO has launched.

Here's the traffic snapshot.

/cc https://github.com/bisq-network/compensation/issues/294

[m52go]

2019.06 Report

This month a number of small adjustments were made to docs (typos, edits, etc). Biggest item was an overhauled compensation doc to reflect new DAO conventions.

Here's the traffic snapshot.

/cc https://github.com/bisq-network/compensation/issues/304

[m52go]

2019.07 Report

This month freimair made a big update to the seednode doc, and huey735 contributed some improvements too (notably, some much-needed additions to the rules doc).

Had a call with some folks from Wasabi and BTCPay who are also trying to migrate to better docs infrastructure. Looking to test a couple options and make a proposal to migrate soon.

Here's the traffic snapshot.

/cc https://github.com/bisq-network/compensation/issues/323

[m52go]

2019.08 Report

Lots of minor updates. Notably, just merged the Matomo tracking code, so we can get rid of Google Analytics on the docs site too.

I am narrowing my search for a new docs infrastructure, and will be making a proposal soon. Apparently AsciiDoc is not supported in many of the popular documentation-oriented static site generators, and I really like AsciiDoc.

Here's the traffic snapshot.

/cc https://github.com/bisq-network/compensation/issues/361

[m52go]

2019.09 Report

I proposed a route to migrate Bisq docs to a more flexible platform, and will start to look for feedback more actively since upcoming changes to docs will make this migration more important.

In the month of September, I started to update the getting-started guide, secure-wallet guide, and rules doc. The first 2 were just merged, while the other is back to [WIP] stage for v1.2 updates.

Otherwise, a placeholder section on mediators was added to the rules doc (complete write-up pending in https://github.com/bisq-network/bisq-docs/pull/167) and asset listing fees were once again clarified, as it turns out per-day fees are now required from the first day an asset is listed.

Here's the traffic snapshot from Matomo. The tracking code was added on September 9, so these are not full-month numbers.

/cc https://github.com/bisq-network/compensation/issues/372

[m52go]

2019.10 Report

Notable changes merged in this cycle included a full overhaul of the Rules document for v1.2 and a fully-new Payment Methods doc that includes guidance on Account Signing.

Other small changes were made throughout the repository to reflect the changes in v1.2.

Here's the traffic snapshot from Matomo. I'm using the "Page Titles" view this time since the filenames view used last time included duplicates.

/cc https://github.com/bisq-network/compensation/issues/408

[m52go]

2019.11 Report

It seems the knowledge base being discussed to add as part of the new support initiative might have an impact on how documentation is situated within the archive of Bisq knowledge. Preliminary discussions indicate documentation will become more of an evergreen record of infrastructure, roles, and underlying principles, whereas the knowledge base will become more of an adaptive practical resource for support and how-to guides.

Here's the traffic snapshot from Matomo. The new payment methods doc merged in the last cycle is doing especially well.

/cc https://github.com/bisq-network/compensation/issues/442

[m52go]

2019.12 Report

Nothing notable to report. Knowledge base should go live in Cycle 10 (upcoming cycle), which means docs will probably start to see changes soon afterward.

Here's the traffic snapshot from Matomo.

/cc https://github.com/bisq-network/compensation/issues/471

[m52go]

2020.01 Report

It seems docs will be replaced with a wiki, so this role may not be relevant for too much longer.

Here's the traffic snapshot from Matomo.

/cc https://github.com/bisq-network/compensation/issues/497

[m52go]

Cycle 11 Report

There were a couple of minor updates in this cycle, but nothing significant.

As detailed here, I would like to replace the getting-started page in docs with a more friendly, interactive page on the website.

Here's the traffic snapshot from Matomo.

/cc https://github.com/bisq-network/compensation/issues/513

[m52go]

Cycle 12 Report

Migration to the wiki continued. I added documentation on arbitrators, the burning man, and the arbitration process itself, along with doing a couple of stylistic edits here and there.

No changes to the docs repository though.

For completeness, here's a screenshot of traffic.

/cc https://github.com/bisq-network/compensation/issues/540

[m52go]

Cycle 13 Report

No activity in the past cycle.

Lately I've started to make an intentional effort to get the wiki under control, so that we can get out of this weird no-man's-land it feels like we're currently in (i.e. neither site is an overall authoritative resource) and complete the migration sooner rather than later. The wiki will be getting more traffic soon as a result of wiki articles being linked on the new getting-started page on the website, so it needs to be tidied up anyway.

/cc https://github.com/bisq-network/compensation/issues/572

[m52go]

Cycle 14 Report

Wiki rolled out 3 days ago, so docs can start being decommissioned. A lot of articles have already been transferred.

I'm thinking it might be best to convert some of the more notable items like the Phase Zero doc which don't seem appropriate to recreate on the wiki into PDFs.

/cc https://github.com/bisq-network/compensation/issues/604

[m52go]

Cycle 15 Report

Not much to report. With the wiki now rolled out and most major pages transcribed, I will start linking pages on the front page of the docs website to the wiki.

/cc https://github.com/bisq-network/compensation/issues/631

[m52go]

Cycle 16 Report

A pull request is in review to start linking docs to the wiki.

/cc https://github.com/bisq-network/compensation/issues/649

[m52go]

Cycle 17 Report

@Bayernatoor and I (but mostly him) are working to transfer DAO docs to the wiki.

The PR mentioned in my last report was merged, so many links on the docs front page now point to the wiki.

/cc https://github.com/bisq-network/compensation/issues/676

[m52go]

Cycle 18 Report

Initiative to transfer DAO docs to the wiki continues.

/cc https://github.com/bisq-network/compensation/issues/702

[m52go]

Cycle 19 Report

Didn't make any progress on transferring docs to wiki, although I did edit some wiki articles.

[m52go]

Cycle 20 Report

Might be getting some new help for docs in the new year. Looking forward to shutting down the old docs website in Cycle 21 or 22.

[m52go]

Cycle 21 Report

Not much to report yet. Announced restart of initiative to move DAO docs to wiki on Keybase; shooting to get it done in Cycle 22.

/cc https://github.com/bisq-network/compensation/issues/775

[m52go]

Cycle 22 Report

Still looking to get DAO docs moved to wiki before this cycle actually ends. Also want to move website FAQs to the wiki for better maintainability.

[m52go]

Cycle 23 Report

Not much to report. See Cycle 24 report.

[m52go]

Cycle 24 Report

The docs website is now ready to be shut down. We just have to wait for v1.6.5 to be released, which will include PRs (already merged) to remove lingering docs links from the software.

After that release has attained good usage, docs.bisq.network can be shut down, and docs.bisq.network can be redirected to bisq.wiki.

[m52go]

Cycle 25 Report

v1.6.5 was released on May 29, and docs.bisq.network was decommissioned on June 15.

[m52go]

@cbeams this issue can be closed. Although the site is still up, the role is no longer relevant.

I recommend shutting the site down too because people still link to it specific pages every now and then, and those page-specific links don't redirect to the wiki.

[cbeams]

Closed as requested. I've made a note to self to shut down the site, or to do a global redirect to the wiki.

[cbeams]

Update: I've also deleted the @bisq-network/docs-maintainers team accordingly.

[pazza83]

Closed as requested. I've made a note to self to shut down the site, or to do a global redirect to the wiki.

Looks like the 301 redirect was applied to the home page but not all the pages.

eg: https://docs.bisq.network/ 301 redirects to https://bisq.wiki/Main_Page

... but for example

https://docs.bisq.network/getting-started-dao-traders.html does not redirect.

Would it be possible for someone to 301 redirect every page in the docs.bisq.network to the corresponding page on bisq.wiki ?

I think every page has been created on the wiki.

The reason being is the docs.bisq.network still ranks well is search engines but as it is not longer active some of the information is now outdated. It is not immediately obvious for visitors to docs.bisq.network that it has been retired if they land on a page other than the home page. Occasionally users with support needs reference outdated information on the docs site and it can cause some confusion.

Looks like there was an issue created to do so here: https://github.com/bisq-network/bisq-docs/issues/210

I think it would be good to expand the 301 redirect to be site wide.

Tagging in @cbeams and @m52go

[cbeams]

Looks like the 301 redirect was applied to the home page but not all the pages.

eg: https://docs.bisq.network/ 301 redirects to https://bisq.wiki/Main_Page

... but for example

https://docs.bisq.network/getting-started-dao-traders.html does not redirect.

That's right. You can see it expressed as the 'Page Rule' with position 1 below:

Would it be possible for someone to 301 redirect every page in the docs.bisq.network [...]

Yes, this could be done simply by modifying the page rule to include a catch-all asterisk, e.g.:

docs.bisq.network/*
Forwarding URL (Status Code: 301 - Permanent Redirect, Url: https://bisq.wiki)

[...] to the corresponding page on bisq.wiki ?

Unfortunately, this is not directly or cheaply possible. Do have a custom redirect mapping every page on docs to every page on the wiki would require one Page Rule per redirect, and additional Page Rules are a paid feature at Cloudflare.

It might be possible to handle the redirect on the wiki side via MediaWiki redirect configuration, but I don't know. If it is possible, then the more inclusive redirect detailed above would be all we need to do on the Cloudflare side. @pazza83, maybe you could look into the possibilities with MediaWiki redirects?

@pazza83, let me know if you'd like me to enable the more inclusive redirect. If we do so, it might be also be good idea to relax it from a 301 to a 302.