Create a "Guidelines" section in the guide

[Bosch-0]

Hey guys,

Wanted to propose an idea for a new section in the guide I've tentatively been calling "Guidelines." This chain of thought has mostly arisen from the interviews Mo and myself have been conducting with users of the guide. We are currently in the process of formalizing this into a report which should be out soon. You can watch the recordings of these interviews here.

But a common theme among most product builders we talked too is that the guide lacks specific recommendations on common, as well as not-so common, bitcoin user problems and scenarios.

We got a lot of praise for our reference designs and other content in the guide for helping with onboarding, sanity checking designers, and giving a broad overview of topics. Though it's not often used to find new, innovative design approach's to bitcoin UX problems - which is what the guide should be doing imo and personally I find these explorations enjoyable.

How would content in this section look?

Simply put, we would have dedicated pages (Guidelines) for unique bitcoin problems, features, BIPs or scenarios. An example could be:

Page title: Key rotation

Page content: Covers how to deal with key rotation, why it's necessary, explorations (what if? ideas). It would likely touch on various topics such as things like FROST, Taproot, collaborative custody etc. It's important that we don't make these too broad and keep the very focused on dealing with a particular user scenario or problem that wallets are facing, or are likely to face soon.

Other examples:

• Multisig
• Collaborative custody
• Addresses (we already have an address page which could be moved to this new guidelines section and expanded upon).
• Stable coins
• Fedimint gurdians
• Fedimint users
• etc...

The idea would be we would identify what guidelines are important through talking with the community and see what is going on in the ecosystem. Smaller bite sizes, focused pages like this would be easier to contribute to as well as keep up to date with changes in the ecosystem.

The reference designs have lot of moving parts which can make the updates (especially considering this is a FOSS project) slower in pace. With how quick the industry moves (especially lightning, and something I experienced personally working on the daily spending wallet) this compounds this friction. Contributing to reference designs you also have to take into context the reference design as a whole which acts as a big point of friction for new and regular contributors alike.

This type of content is similar to how large design guides like Material design and Apple's Human Interface Guidelines create.

[ConorOkus]

Concept ACK

[GBKS]

TBH, this sounds like "Reference designs" to me. You have a specific problem/scenario and provide UX guidance via an imagined product. You mention that reference designs have so many moving parts. I think that's only the case for the daily spending wallet. If you look at the upgradeable wallet, it focuses on a specific mechanism/flow.

Covers how to deal with key rotation, why it's necessary, explorations (what if? ideas). It would likely touch on various topics such as things like FROST, Taproot, collaborative custody etc. It's important that we don't make these too broad and keep the very focused on dealing with a particular user scenario or problem that wallets are facing, or are likely to face soon.

I'd structure this example as two pages. First, a "how it works" page that explains the mechanics and applications. Could be a sub-page to "How it works -> Private key management -> Multi-sig". For specific UX guidance, it could either be a sub-page of the savings wallet reference design, or its own reference design (focused, like the upgradeable wallet on).

As far as specific recommendations, we also have the idea of "case studies" still floating around. If someone does not want to imagine a new product, they can review an existing one and highlight good/bad UX and make recommendations (like the ones by Built for Mars that people seem to like).

Either way, structure follows content (IMHO). As you wrote, let's pay attention to what problems users/designers have, create the right content for that, and then figure out how it fits together (whether that's in existing or new sections).

[Bosch-0]

TBH, this sounds like "Reference designs" to me. You have a specific problem/scenario and provide UX guidance via an imagined product.

A whole reference product is not a specific problem/scenario (which the reference designs are currently). TBH I only see the daily spending wallet as an actual reference design. The others are outdated and more like stubs of that type of product.

Don't get caught up on the example I gave, that was just an example to illustrate the structure of what a page could look like in this section. Where that type of content belongs or not was not the point.

As you wrote, let's pay attention to what problems users/designers have, create the right content for that, and then figure out how it fits together (whether that's in existing or new sections).

Based on the feedback from interviews the type of content I outlined seems to be what product builders want more of.

[moneyball]

From the beginning 3 years ago, I always imagined the bitcoin design guide being guidelines, a set of best practices that are clearly explained and supported through research and design analysis.

[moneyball]

So to be more explicit, I don't understand why we'd add a section to the guide for guidelines, as the entire guide's essence should be about guidelines. That's what the "guide" is in design guide :) What am I missing?

@Bosch-0@GBKS

[GBKS]

I agree, and would just repeat my previous recommendation to not get hung up on categorizations, but just focus on creating useful content first, and then update our structure as needed (flaws will become apparent, as they previously have). Section names do not dictate the content, they follow the content, IMHO.

Let's take that list of topics people are interested in, chat about which ones are the most asked for, and figure out how we can best address them. The result will likely be different than what we imagine right now anyways.

[mouxdesign]

Will start watching and making notes on the video interviews from tomorrow and will create a google doc with some notes. It might aid this discussion.

[sbddesign]

This idea sounds to me sort of like a hybrid between Principles and a Reference Design. It sounds like we're taking a "topic" or "issue", and then just listing out common design considerations, but not necessarily doing an exhaustive series of user flows.

Do we have any idea what these guideline topics might be? Like, are there specific topics people want to find information on but aren't finding?

Regardless, I tend to agree with @GBKS -- first make useful content, then figure out how to categorize it later.

[Bosch-0]

Yeah kind of like that. The "Guidelines" (tentative name fyi) are like little blocks of info on specific topics and then we use these blocks to craft reference designs (which are essentially mock up products).

A cool one would be something like Taro, how would dealing with Taro assets look like, how would issuing them look like? etc.

[cogentgene]

+1 for this idea! I think it is beneficial to have both general best practice guidelines, but also very specific use cases / scenarios with concrete examples of how to overcome that issue.

I was looking for references on Point of Sale devices but didn't see any. The reference design was helpful a bit, not gonna lie, but it would have been amazing to see a specific section on POS design considerations. But it doesn't have to be specific to use case, I guess it could also work for various UX challenges that are more specific to the app.

[GBKS]

Point-of-sale and merchant UX is something that has been talked about for a long time, but so far we are missing a "champion" who can make it happen. Would definitely make for a good case study, as well as several more general pages around merchant and store/check-out UX.

[GBKS]

Either we find a champion, or we turn it into a big project like adding lightning to the guide. Either way, it requires a push and some momentum to get going.