Comments (5)
I don't like the numbering in the TOC, I need to find a solution.
from wiki.
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.
from wiki.
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=692So 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:
- Add a 2nd-level "Steps" heading to encapsulate all the individual steps sections
- Make the individual steps sections 3rd-level headings under the Steps section
- Remove the numbers from the individual step section headings
- return to normal (numbered) WikiText bullet points in the sections themselves
The reasons for doing this:
- 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.
- 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.
from wiki.
Oh. I see now what I considered to be an ugly TOC is the standard, example:
4 1. Get private keys
Ok.
from wiki.
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.
from wiki.
Related Issues (20)
- Edit the "Reduce JVM MAXRam" article HOT 2
- Edit the "Find your mediator" article HOT 7
- Styling UI elements HOT 2
- Determine policy for non-English wiki pages HOT 3
- Specifying wallet derivation path HOT 1
- Designate high-priority articles for translation HOT 4
- Update compensation article HOT 1
- Transcribe DAO docs to wiki HOT 6
- Running_Bisq_on_Tails at least needs a disclaimer HOT 13
- New article: changing onion address HOT 1
- Add to the Amazon Gift card article HOT 1
- Qubes instructions in wiki incomplete HOT 1
- Qubes instructions inconsistent reference to bind-dirs HOT 2
- Penalty for "Buyer makes payment from an account with a different name": define "different" HOT 2
- Add page for BSQ swaps
- Wrong denomination in "BSQ trading fees" spreadsheet HOT 2
- Update Table of Penalties for clarity and readability HOT 1
- Change Cash by Mail info in Payment_Methods HOT 1
- Link on wiki points to empty install_java.sh file
- Add Bisq 2 wiki pages
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from wiki.