Decide on scope and style of use case articles

[Bayernatoor]

I am starting to turn some of the stub pages into actual use cases. Alot of the pages found on docs.bisq.network have quite a bit of explanation and text prior to providing steps on accomplishing a specific goal, e.g. https://docs.bisq.network/getting-started.html#fund-your-bisq-wallet which I turned into https://bisq.wiki/Fund_your_wallet.

I am curious what everyone thinks and whether there is too much information prior to getting to the real 'meat' of the use case. Personally it seems fine to me as long as we don't provide unnecessary information/multiple use cases per page.

[cbeams]

Glad you brought this up. I briefly addressed this topic in last week's screencast, but I think we have to make a conscious decision here. The way the Getting Started guide works at docs.bisq.network is that it does everything on one page, and guides the user through a highly specific use case (buying BTC for USD using Zelle). That's a nice way to go because it puts everything in context and gives concrete instructions as to exactly what the user should do. If we break things up into individual use case articles (like 'Fund your wallet') and aggregate those into lightweight guides like what's currently seen at https://bisq.wiki/Get_started https://bisq.wiki/Get_started, then we'll have to make things at least somewhat more general in the individual use case articles. One could still use the specific example of buying BTC for USD with Zelle, but you can't assume that the user is already aware of that example, as they might be entering into any one of those use case articles "cold", i.e. not from within the larger context of a guide. I think there's a lot of power, flexibility, discoverablity, re-mixability in keeping the docs separate, well-categorized, similarly-structured and as context-free as possible.

A bit of introductory / explanatory text is a good thing, but there doesn't need to be much. The feel should be lean and mean, clear and clean. This will help a lot with authoring new docs and maintaining old ones, as there will be less "wordsmithing" and "voice" to manage. I think minimalism will serve us here. Also, if we look to Wikipedia and the Bitcoin Wiki as examples, there's not a lot of "friendly prose" there; they are factual, objective resources designed to convey information with accuracy and efficiency. There isn't a lot of hand-holding, congratulations or exclamation points, if you know what I mean. We should strive for the same.

On Mar 2, 2020, at 6:43 PM, Bayer notifications@github.com wrote:

I am starting to turn some of the stub pages into actual use cases. Alot of the pages found on docs.bisq.network have quite a bit of explanation and text prior to providing steps on accomplishing a specific goal, e.g. https://docs.bisq.network/getting-started.html#fund-your-bisq-wallet https://docs.bisq.network/getting-started.html#fund-your-bisq-wallet which I turned into https://bisq.wiki/Fund_your_wallet https://bisq.wiki/Fund_your_wallet.

I am curious what everyone thinks and whether there is too much information prior to getting to the real 'meat' of the use case. Personally it seems fine to me as long as we don't provide unnecessary information/multiple use cases per page.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/bisq-network/support/issues/352?email_source=notifications&email_token=AACJV4VLUZPPIUFUDM3HH43RFPV2JA5CNFSM4K7ZHHBKYY3PNVWWK3TUL52HS4DFUVEXG43VMWVGG33NNVSW45C7NFSM4IRYUT4Q, or unsubscribe https://github.com/notifications/unsubscribe-auth/AACJV4VRZLXCXXVZGYG3KNLRFPV2JANCNFSM4K7ZHHBA.

[m52go]

A bit of introductory / explanatory text is a good thing, but there doesn't need to be much.

Indeed. Check out the getting started page on the Bitcoin wiki...might be extreme, but it still manages to work.

Perhaps we can start to use the blog as a medium that uses voice and wordsmithing to outline particular use cases. It's not uncommon for blog posts to be tutorials...many wind up getting amazing SEO rankings too.

[cbeams]

Btw, @Bayernatoor, I would rename this issue to reflect that it's really about deciding on the scope and style of our use case articles. I'd recommend then creating individual issues for each page that you / others work on, so as to be able to complete them in a concrete way. "Creating new use case wiki pages" is not a task that can really be completed without further definition. Note that these issues can be added to the Roll out Bisq wiki project for tracking purposes. Some similar issues already have been.

[Bayernatoor]

Yep the malleability of having individual use case pages could be really beneficial as the wiki grows in size and keeping it to the point and professional should also help give Bisq a strong image.

Rename is noted. As for opening an issue for each page made, some pages are 5 - 10 minutes of work, do we think opening issues for those is worthwhile? I suppose it does give us an area to discuss and consider changes to the pages if necessary.

[Bayernatoor]

Also, did you mean adding each issue here - https://github.com/bisq-network/projects/labels/to%3AImprove%20Support ?

[kemccall]

@Bayernatoor @cbeams @m52go

I think/hope this is appropriate here. If not please advise me otherwise.

To start from a bit bigger picture, information (almost any technical information) falls into three broad types, a 1) concept, 2) reference, or 3) procedure, and some may consider troubleshooting another type. This is the fundamental guide to the structure of use cases.

Documents get confusing when these types of information are intermingled. The "Getting Started with Bisq" section is an example of mixing these types of information - with the addition of troubleshooting information, marketing info, notes, warnings, background information and more.

I understand what's trying to be accomplished, and it's a great work! Obviously the author(s) put a lot of thought and work into it and should be commended. But, it can be improved. It's a complex process with several procedures, and a background in many of the areas is necessary to complete a transaction.

Granted, this section is attempting to be a tutorial, and tutorials will in fact have instructional material in them, but the instructional and background information needs to be minimal. In short, this section needs to be a bit more structured and the information types segregated. A conceptual introduction, with an overview of the process followed by a succinct, non-verbose procedure.

It may, at some point, become individual use cases, but I wouldn't try to accomplish that initially. We just want to create a guide to get a user successfully through a transaction. AND THEN through other non Zelle methods.

[Bayernatoor]

Hey @kemccall

I've been mostly trying to migrate any information from https://docs.bisq.network/index.html to the wiki. However, the docs tend to be very detailed and the sections contain a wide range of information, from basic BISQ concepts to use cases and more.

Therefore, what @cbeams has been trying to do is implement a complete different approach to the wiki and i think you seem to be on the same page in regards to format as him. Short, succinct articles which can then be referenced and linked to. Do away with the flare and just provide accurate information. I hope I am correct in my assumption, otherwise please let me know.

Here are a few examples of pages that I've created. in my mind #1 is probably the closest to what were going for. #2's intro may too long and may include too many details and #3 was just a quick explanation of how trading fees work in Bisq. 2 and 3 were essentially copied over from the original bisq docs.

1. https://bisq.wiki/Delete_and_resync_SPV_file
2. https://bisq.wiki/Payment_methods
3. https://bisq.wiki/Trading_fees

What are your thoughts on this. Bisq seems to have very specific steps to get from install to purchasing Bitcoin. Therefore, i am concerned that creating guides with too little detail may leave the user looking for answers. However, i am new to this whole wiki business and am here to learn. Personally i prefer articles that are to the point and concise.

[kemccall]

@Bayernatoor Yes, you're exactly on target with your concept. No one likes to read for information. Reading for information is work. In fact, I have yet to do a Bisq trade, in no small part, because of the initial info.(I want to do a money order trade)

That being said, IMO there needs to be a degree of friendliness. This is always a trade off.

I wondered who, how, and how much information has been converted.

I'll take a look at you example a bit later today.

Ken

Sent with ProtonMail Secure Email.

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Saturday, March 21, 2020 12:48 PM, Bayer notifications@github.com wrote:

Hey @kemccall

I've been mostly trying to migrate any information from https://docs.bisq.network/index.html to the wiki. However, the docs tend to be very detailed and the sections contain a wide range of information, from basic BISQ concepts to use cases and more.

Therefore, what @cbeams has been trying to do is implement a complete different approach to the wiki and i think you seem to be on the same page in regards to format as him. Short, succinct articles which can then be referenced and linked to. Do away with the flare and just provide accurate information. I hope I am correct in my assumption, otherwise please let me know.

Here are a few examples of pages that I've created. in my mind #1 is probably the closest to what were going for. #2's intro may too long and may include too many details and #3 was just a quick explanation of how trading fees work in Bisq. 2 and 3 were essentially copied over from the original bisq docs.

• https://bisq.wiki/Delete_and_resync_SPV_file

• https://bisq.wiki/Payment_methods

• https://bisq.wiki/Trading_fees

What are your thoughts on this. Bisq seems to have very specific steps to get from install to purchasing Bitcoin. Therefore, i am concerned that creating guides with too little detail may leave the user looking for answers. However, i am new to this whole wiki business and am here to learn. Personally i prefer articles that are to the point and concise.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[kemccall]

@Bayernatoor Took me a couple of minutes to determine that the hyperlinks #1, #2, and #3 are not what you're referencing. 8-)

Here's information (any technical information) in a nutshell. There are 3 types of info (almost always):

• Concepts
• References
• Tasks

These should not be intermingled (described further on).

_https://bisq.wiki/Delete_and_resync_SPV_file_ is a darn good write up. I'm impressed for someone who's not a professional writer (my assumption).

It's a Task, with the introductory paragraphs being Conceptual. That's OK. You've kept the Task and Concept separate (not intermingled). There are a number of things I would do to tighten it up both grammatically and technically, but that's what a Technical Writer/Editor does (my real job).

What I do is make changes, some of which are recommended, some are technical in nature and some are simply style issues. I'll do that in a separate topic.

The mechanics of how we do this I think we both need to decide upon. But before we go there, let's look at _https://bisq.wiki/Delete_and_resync_SPV_file_. It's a different animal. It is both Concept (the first 4 paragraphs) and Reference (most of the remainder). You're also exactly right in that it's verbose with a lot of "fluff" (perhaps unrelated info).

_https://bisq.wiki/Trading_fees_ needs some work. It's striving to be a concept, but it's got other stuff intermingled. BTW some of it I recognize as things that have made me hesitate in making a Bisq transaction. But, we'll save that for later 8-).

[kemccall]

@Bayernatoor So how do we work together? Let's take _https://bisq.wiki/Delete_and_resync_SPV_file_ for a test run. I'll simply make the changes that I think should be made on the wiki page and add some explanations (as needed) in the Discussion tab. Or maybe as comments in. the wiki

It's a small topic, so lets see what works and/or doesn't. I think the only drawback may be that you can only revert to the original version, nit the incremental changes (I think...?)

[kemccall]

@Bayernatoor I added a lot of inline comments and nothing in the Discussion area.

IMO the Help! I Can't Access the Bisq Settings Screen is a separate use-case.

Also, I think that the style for buttons needs to be more distinct and different than code but I'm not sure what at this time.

Also, the history is a nightmare due to my fumbling with styles. Sorry.

[kemccall]

@Bayernatoor Looking at it now in hindsight I'm wondering if the title might be better as "Wallet does not display correct balance". The title now is describing the solution to a problem. People will search for their problem, they won't search for a solution that they don't know. Unless there's some other context for this that I'm unaware of.

[kemccall]

@Bayernatoor Just now discovered a good reason to NOT use inline commenting when communicating changes - while the comments do not appear in the use case, they DO appear in the search results! Ugh.

[Bayernatoor]

@kemccall - I appreciate the feedback on #1, i am not a professional writer.

The modifications that you've made to it are very straight to the point and removes anything considered 'off' topic. I took a look at the comments and it's clear that I mentioned certain things which did not include any further explanation. Limiting the info provided is key. Overall it gives me a better sense of what we're trying to accomplish here.

The mechanics of how we do this I think we both need to decide upon. But before we go there, let's look at https://bisq.wiki/Delete_and_resync_SPV_file. It's a different animal. It is both Concept (the first 4 paragraphs) and Reference (most of the remainder). You're also exactly right in that it's verbose with a lot of "fluff" (perhaps unrelated info).

I assume you meant page #2 - https://bisq.wiki/Payment_methods. Considering the changes you made to the previous page, I'd remove the intro and make this page purely a reference.

3, I agree, too much explanation of what coloured bitcoin is, this concept, should be explained elsewhere. The page should be a reference page on trading fees.

IMO the Help! I Can't Access the Bisq Settings Screen is a separate use-case.

Agreed, we can link to it at the end of #1.

Also, I think that the style for buttons needs to be more distinct and different than code but I'm not sure what at this time.

You mean instead of bolding the text?

@Bayernatoor Looking at it now in hindsight I'm wondering if the title might be better as "Wallet does not display correct balance". The title now is describing the solution to a problem. People will search for their problem, they won't search for a solution that they don't know. Unless there's some other context for this that I'm unaware of.

The reason this title was selected is that this is often the first solution to most problems encountered with Bisq. Kind of a, let's try this first then investigate further if that doesn't solve it. So perhaps we change the title and as we create more 'problem wiki pages' we link to it as step 1? Or we keep it as is and use it as an across the board solution, may need a new title anyway.

@Bayernatoor Just now discovered a good reason to NOT use inline commenting when communicating changes - while the comments do not appear in the use case, they DO appear in the search results! Ugh.

Aha, yeah we can discuss it here, seems to work well. Especially if we make individual issues for each page. @wiz created this project board for that purpose. https://github.com/bisq-network/wiki/projects/1

[kemccall]

@Bayernatoor I don't see a method for discussion on https://github.com/bisq-network/wiki/projects/1 maybe I'm missing something?

[kemccall]

@Bayernatoor In regards to the "Delete and Resync SPV file" use-case - is there a finite list of problems that require this use-case as a fix? Or, are there many possibilities?

[Bayernatoor]

@kemccall Hmm i seem to remember being able to open the items on the board and add comments. Still not very knowledgeable with Github. Another option would be to open issues https://github.com/bisq-network/wiki/issues for each page.

[Bayernatoor]

@Bayernatoor In regards to the "Delete and Resync SPV file" use-case - is there a finite list of problems that require this use-case as a fix? Or, are there many possibilities?

Good question. there's certainly a finite list, but that list may be long. Perhaps @huey735 and @MwithM can comment as they have been around much longer then I have.

[kemccall]

@Bayernatoor @MwithM @huey735 @cbeams So, here's what we need to do for this use-case and most others in the future. Unless there's a direct link to the use-case, we need to create a title that someone experiencing the problem(s) might search for. What we have now is a title that IS the solution. It's unlikely that anyone will search for a solution that they already know.

So, perhaps the list you have is extensive but not known to be complete. (Which I suspect is likely.) We come up with the best generic title that we can, and in the textual area I'll list the known problems so that they will also enter into the SEO algorithm when someone searches for a solution to their problem.

Me not being as we say in the tech writer field, a subject matter expert (SME), I will enlist your help determining a great title that hopefully leads the user to any of their problems.

[Bayernatoor]

Hey @kemccall an SPV re-sync may be necessary for the following:

1. Wallet balance displaying incorrect amount
2. Corrupted SPV file
3. Transaction to or from Bisq not appearing
4. Any sort of invalid Tx - an SPV re-sync helps clean them up.

This is a partial list but in reality it seems to be mainly used for wallet balance display issues/ incorrect information displaying. So perhaps any of the following:

1. Bisq displaying incorrect information.
2. Bisq first step to problem resolution

Honestly, i think the title we have now is okay, as you said, if adding some of the most common issues onto the page helps with google searches then the title shouldn't matter too much. We also suggest that people try a re-sync as a first step to most problems.

[pazza83]

Closed as stale