Editorial policy discussion for new proposals with little or no adoption

[GBKS]

A question around guide content policy has come up in the context of PR #1082 that adds a page describing UX approaches to BIP353 (DNS payment instructions). If I read things correctly, the BIP was first proposed in the bitcoin repo on February 10, and assigned a number on June 3. Pretty new, for sure. And I think this is the first time that we create guide content as a BIP is being finalized.

On a side note, I personally always saw BIPs as a very serious reference. If something has a BIP number, it must be good to go, right? Well, maybe there's more to it. The BIP repo README provides a point of view.

@BitcoinErrorLog has raised a strong concern about including content about a new proposal that has not proven its place in the world yet. Please read those concerns, and then let's discuss and find a way forward, for this situation and possibly for future additions.

I will try to stay out of the decision, being a maintainer and having created the PR in question. Having said that I'd still like to start this conversation off (and you are welcome to ignore that) with two different views of the guide:

1. A more conservative view would be to only include things that have found some type of minimal adoption. Maybe 3-5 broadly used wallets need to support a feature.
2. A more forward-looking view would be to also include speculative things. This would allow for broader exploration, and probably the addition of appropriate labels to ensure readers understand how things are meant. There could also be content that explores concepts and then advises against using them, which could also be helpful to readers. I think that the Stabilizing bitcoin value page falls into this general exploratory bucket.

Case-by-case decisions are required either way.

Practical outcomes of this discussion could be:

• A clarification of content policy (for example in the Content guidelines page)
• The PR could either
  • Get changed to draft status and remain a PR until the point the BIP becomes broadly adopted (if ever)
  • Get closed and the content could be published elsewhere (maybe I can put it on my blog for now)
  • Get published, possibly with addition of edits and disclaimers to address concerns

That's probably enough from me here. Feel free to ignore any perspectives I consciously or subconsciously slipped into this text and I'd love to hear what you think. I'll ping a few people who have been involved with the guide, feel free to invite others. Thanks in advance.

[BitcoinErrorLog]

Reposting my most recent comments on the topic here for convenience:

I remain totally opposed to including non-standard, not-used, speculative proposals inside of something that is meant to be a general guide. It is inaccurate for the context, misleading, and potential king-making behavior. (referring to the "BOLT12" bitcoin address proposal from Matt, which is by no means accepted by anyone, anywhere. Nor is there anything even close to a consensus that this should be done.)

I suppose I am commenting on overall Guide policy. I assume a goal is being a resource for onboarding designers & related roles into conventional, and even modern, knowledge and examples that may be relevant to their work.

I agree that neither of us could effectively measure the effectiveness of any king-making behavior, I just mentioned it as something best avoided altogether. And it is certainly avoidable if we agree on the goals.

You could do as you mention and require a certain standard of adoption, or other approaches, or even clarifying the goals to include being a resource for any known Bitcoin proposals, or Spiral proposals, or regardless of relevance, as long as they are Bitcoiny, like Runes, etc.

In the end, my opinion is simply that I imagine the target user of the guide will expect a certain amount of standardness and practicality to the advice contained within it, and I don't know a good argument for including speculative, unsupported proposals like this one.

I certainly defer to you and the people putting the actual work into this! Just trying to help.

[BitcoinErrorLog]

Additionally, it is important to note that BIPs are not a form of consensus, adoption or legitimacy. BIP maintainers make it very clear that it is a resource of proposals, and the only vetting they do is objective in nature, confirming the form of the proposal is acceptable and meets minimum requirements in structure, etc.

There can be conflicting BIPs for two different solutions, BIPs that no one actually adopted, and even BIPs that are purely aesthetic in spec, without any code as a topic at all.

If the Bitcoin Designers want to provide prototypes, guides, and UX hints for BIPs directly, that might be a more appropriate way to contribute to unsupported new BIPs than adding them to a general guide for designers.

For example, at Synonym we have several spec proposals that we would be comfortable submitting as a BIP, but not comfortable submitting to the design guide (for lack of adoption/implementation).

[paulosacramento]

Excellent point @BitcoinErrorLog. Thanks for bringing this up.

Ever since I read your comment I have also had this question in the back of my mind.

• Is the Bitcoin design community making kings?
• Are we spending too much energy and time designing for standards that may never take off?

My opinion: I think it is perfectly fine for us as a design community to do our part to push a certain standard. As long as there is a rough consensus around it, I don't see why it would be a problem. We have an understanding of the principles that guide our decisions: usability, privacy, censorship resistance, etc. If a brand new standard comes along that improves these aspects in a balanced way, we should do what we can to help it become known and implemented.

The only condition for this would be:

• Describe the new proposal as new and not widely accepted
• Mention other competing proposals in an unbiased way

What is really important is to wnsure that the assessment is fair and transparent. In other words, as long as the content is honest and unbiased, everything is fine.

If @GBKS, as the maintainer, feels that the consensus is unclear, he can ask about it on social media, or use a pool, to check the overall mood.

[yashrajd]

Lots of good points made here and the PR so I extracted points made by both, but I also included @moneyball comments from Discord that seemed relevant (file here).

[yashrajd]

My 2 sats:

• should newer rough-consensus-but-not-standard-yet content be included? YES; otherwise the Guide will only be useful for projects/designers totally new to bitcoin and miss the opportunity to help adoption of newer, concept-ACK ideas. Eg: bolt-12 or silent payments

• NO, if some proposal has neither adoption nor consensus (IMO BIP-353 might fall under this currently)

I think there is another point w.r.t content policy here: WHERE (affects HOW) in the guide or website should content be included.

[sbddesign]

It's an interesting question. I've voiced similar concerns back in 2022 in github convos as well as in video/IRL conversation. My take was that the Guide should not be something that chooses selects which technologies or protocols should and should not get adopted.

There's a difference, of course, between recommending something and talking about it.

My take would be that the Guide approaches thing first from meeting a user need. A Guide recommendation might be: "build products that promote self-custody". NOT "build products that promote BIP-39 Seed phrases". However, in the course of writing an article about building products that promote self-custody, it's useful to talk about this user benefit or user need in terms of what's actually possible today. So you might say "hey, one way to promote self-custody is by using seed phrases. BIP-39 seed phrases are the most commonly accepted way to do this". That's a scenario where (I think) we have pretty clear consensus. And you might follow that up with "there are other ways to do seed phrases, but they are not used as commonly".

In other situations, we might be talking about an idea that has multiple implementations with different trade-offs and no clear consensus. For example, take an article that says "you can build products that help users hold a fiat balance alongside their bitcoin balance". You might say "there are several different ways to do this: stablesats, fedimints, custodians, stablecoins, DLCs, etc...these each have pros and cons, so consider the pros and cons for your users". There's not a recommendation here, it's just laying out that there are different ways to do this and they all have tradeoffs.

Of course, there's tradeoffs to be made. Some implementations of an idea don't support the principles of the Guide (self-custody, security, inclusion, interoperability, transparency, privacy, decentralization). Some ideas have actually achieved wide adoption without supporting these principles (for example, KYCing people to get bitcoin is widely adopted but you don't see that being recommended in the Guide). Some ideas do support these principles, but are brand new and not implemented, not widely tested, or not widely adopted. Some ideas have been around for a while and have proven to be insecure, or have been replaced with better, more modern alternatives. All these things need to be weighed,

My rough editorial framework sketch

• Focus first on meeting a user need or desire
• Once the need/desire is outlined, talk about methods to meet this need
• Don't go into gratuitous detail about these methods -- those are for the dev docs
• Prioritize methods that support the principles of the Guide
  • sometimes the method that honors ALL the principles or MOST of the principles is not widely adopted or new and untested. If so, be open and say "this is new", "this not widely adopted", etc.
• There are times where its difficult to meet all those principles -- talk about methods that don't meet all these principles if:
  • they don't violate all the principles (otherwise, what's the point?)
  • they have wide adoption in many wallets OR they have a large seemingly happy user base
• But be sure to mention the tradeoffs of these methods!

[moneyball]

being a resource for any known Bitcoin proposals, or Spiral proposals

The bitcoin design guide is in no way a resource for Spiral proposals. BOLT 12 was a proposal by Rusty. The genesis to BIP 353 is a proposal by t-bast. Neither of whom are affiliated with Spiral.

Hard to take John seriously when he insinuates such things.

[moneyball]

I personally always saw BIPs as a very serious reference. If something has a BIP number, it must be good to go, right?

Being assigned a BIP number in no way means it is "good to go." The bar for being assigned a BIP number is very low.

[moneyball]

(referring to the "BOLT12" bitcoin address proposal from Matt, which is by no means accepted by anyone, anywhere. Nor is there anything even close to a consensus that this should be done.)

There's already rapid adoption by Phoenix, Zeus, Strike is very close, and several more in the works. It is fine to make the case that is in in the early phase of adoption, and the design guide should always point out the level of adoption of any suggested best practice that requires interoperability, but let's at least be truthful about the state of adoption and momentum.

[moneyball]

As for what the guide should be, IMO

1. It should be the best reference guide for someone building a bitcoin application.
2. Thus, if there are new design options that have clear improvements over old ones, they should either replace the old, or, if there remain benefits to the old proposal (such as, existing adoption/backwards compatibility), then the guide should describe the tradeoffs. The guide should also illustrate best practices for achieving backwards compatibility and minimizing user experience awkwardness. (this has been discussed/stressed in numerous BOLT 12 design meeting with @sbddesign and me.
3. If there are competing proposals then that would need to be analyzed by the design guide contributors. However, in the case of BIP353, I'm aware of no other human readable name proposal based on BOLT 12. And BOLT 12 has years of development, support for all 4 major LN implementations, has interoperability testing, and has rapid adoption the past 3-4 months by wallets.

[ConorOkus]

Great points made by everyone in this thread, in general, the bitcoin design principles should be at the core of deciding what makes its way into the guide. BIP353 seems to adhere to all of these principles from what I understand.

If we look at the current payment request format page can we say everything included there does the same? It seems mostly yes but maybe 1 or 2 are up for debate? At the minimum BIP353 should be included on this page as these are very much surface level descriptions of the various options available.

I think what would be more interesting is crafting some case studies around these specific formats, we might do this in a few ways:

• Identify existing FOSS Bitcoin projects that have implemented one of these formats in a user-friendly way and break down all the things they did well.
• Document instances where the bitcoin design community actively collaborated with a FOSS bitcoin project to improve the UX around a specific payment format
• Document instances where a FOSS bitcoin project independently used the guide to improve the UX around a specific payment format (bit harder to know if this has happened in practice)

I think it's a positive to also include more speculative things but we could frame them as "UX ideas and experiments" or just link out to others work or include it in the newsletter might be another option.

[yashrajd]

I have updated the Figjam to include inputs from Conor and Stephen.

What would you all think about below attempt at summary? *Did I miss something? Hope this is useful...

• Guide content should revolve around 3 criteria: alignment with principles, community consensus, community adoption
• Guide should cover newer or emerging developments in addition to recommendations covered in Reference Designs as long as they align with at least 1 of the above criteria
• There should be appropriate communication/demarcation/labelling when content veers away from 1 or more criteria mentioned above