Edit - Manual payout article

[kemccall]

@bisq-network/bisq-devs @wiz

Significant edits to https://bisq.wiki/Manual_payout

Here are the differences:

https://bisq.wiki/index.php?title=Manual_payout&type=revision&diff=821&oldid=692

Changes include:

• Phrasing to change tense from future, to present imperative,

• Styles

• Simplified some statements

• Added nested numbering (html as wiki does not accommodate)

• References to previous sub steps, example, 1.a, 1.b etc. - please check!

[kemccall]

I don't like the numbering in the TOC, I need to find a solution.

[cbeams]

I don't like the numbering in the TOC, I need to find a solution.

See my comments regarding this and other matters in our Keybase chat.

[kemccall]

Chris' comments on Keybase for reference:

Hey Ken. Glad to hear. I see the issue you just created at #22. A few tips:

The way you've done this, it reads as an after-the-fact announcement of the changes you've made. I realize that's a reflection of the reality of the situation, but you may like to know that people may not be sure what to do with this because of the way it's written.

The idea with these issues is that they represent a task. So the task in question here is to "Edit the manual payout article". Ideally, the description of the issue would contain your notes on what you plan to do (if any), or at minimum just a link to the article.

Then, as you're doing the work, you would add comments as necessary, perhaps @mentioning certain people if you have specific questions or want to get the attention of someone specific. I mentioned @wiz and @bisq-network/bisq-devs earlier merely as examples, not as an indication you should mention them specifically.

When you're finished with the edits, you would ideally post a link to the diff between the article as it existed before your edits and its current state, after your edits. You can get this link in the View History tab of the page in question. For example, here are all the edits you made, in one diff: https://bisq.wiki/index.php?title=Manual_payout&type=revision&diff=821&oldid=692

So you would post a comment on the issue with that link, asking for any feedback, and you'd probably move on to your next task. To get folks' attention, you might paste a link to the GitHub issue in the #wiki channel. It's often a good idea to "overcommunicate" these changes just to make sure everyone is aware. In any case, you can wait for feedback to come in on that issue, and if it does, great, you can fold it in as appropriate, and if not, you can eventually just close that issue.

When you do your compensation request at the end of each cycle, you can go back and reference all these issues as a way of accounting for the work you did. We can talk more about how that works later, and you can study the documentation on doing compensation requests / look at other folks' compensation requests to see how it's done.

Finally, a note on the actual changes you made the manual payout article. I notice that you replaced WikiText markup bullet points (*) with HTML order lists and list items (<ol>, <li>, etc). I understand why you did this in order to get the lettered bullet points under the numbered headings. It's a shame that WikiText doesn't make this possible without having to drop down to HTML. I would suggest (but I do not feel super strongly about it) that you do the following instead:

1. Add a 2nd-level "Steps" heading to encapsulate all the individual steps sections
2. Make the individual steps sections 3rd-level headings under the Steps section
3. Remove the numbers from the individual step section headings
4. return to normal (numbered) WikiText bullet points in the sections themselves

The reasons for doing this:

1. To keep the markup as simple as possible to correctly write and edit; basically to avoid the need for HTML except in places where it's really necessary.
2. To avoid the need to renumber section headings manually if steps are added or removed from the process in the future.

I personally don't think the value of having the steps explicitly numbered is worth the weight of the more cumbersome syntax and having to maintain the sequence of numbers manually. Your opinion may differ, of course.

Finally, I wonder why you declared __NOTOC__ at top? Generally, we want a TOC on every article, and I believe you'll see this is the norm. Having a TOC on this page will go a long way to obviating the need for explicitly numbered steps as well; because the user can instantly see that there are a series of steps (in the Steps) section, and can get a sense that there are roughly 10 of them. There is little need for the numbers as reference (e.g. telling a user to "go to step 5", because we can always just provide an anchor link to the specific step's section itself—and having the TOC present makes these links available and easily copy-pasteable.

Normally, I would share the feedback above more publicly, especially the specific notes on content and style. But I thought I'd do it all here in our 1:1 chat this time around just to make sure everything makes sense, and to take any perceived pressure off. Feel free to paste any or all of this into the GitHub issue if you'd like to make it public record. In any case, let me know if this feedback works for you. I can't always take the time to provide it in this level of detail, but I figured it's worth really sitting down and going through some of these things this time around. Hope it helps!

P.S.: otherwise the edits look great and the doc reads better for them. Thanks!

P.P.S: Thinking about things holistically, we should also consider as part of editing this page what to do with the (legacy) document at https://docs.bisq.network/manual-dispute-payout.html. At a minimum, we should add a prominent admonition to that page saying it's out of date and that the new documentation is at https://bisq.wiki/Manual_payout, but it probably makes sense to actually remove that page entirely now and put a redirect in place to the new wiki page so it's all just automatic. Steve (@m52go) can help with this. This is a good example of how we can/should incrementally deal with the content at docs.bisq.network.

[kemccall]

Oh. I see now what I considered to be an ugly TOC is the standard, example:

4 1. Get private keys

Ok.

[cbeams]

Chris' comments on Keybase for reference:

I just updated what was pasted above for formatting. It's possible to copy-and-paste the original Markdown text from Keybase (click ... > copy text on the message itself) here into the GitHub issue, which makes things much better.