[bisq-network/support] Creating new use case wiki pages (#352)

Chris Beams notifications at github.com
Mon Mar 2 19:05:21 UTC 2020


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 at 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>.
> 



-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/bisq-network/support/issues/352#issuecomment-593564761
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.bisq.network/pipermail/bisq-github/attachments/20200302/a575a671/attachment.html>


More information about the bisq-github mailing list