Sure - but in the real world that mostly only happens when the documentation is an afterthought.

Here’s a tip on good documentation: try to write the documentation first. Use it as your planning process, to spec out exactly what you’re going to build. Show the code to people (on GitHub or on a mailing list or on lemmy or whatever), get feedback, change the documentation to clarify any misunderstandings and/or add any good ideas people suggest.

Only after the docs are in a good state, then start writing the code.

And any time you (or someone else) finds the documentation doesn’t match the code you wrote… that should usually be treated as a bug in the code. Don’t change the documentation, change the code to make them line up.

You don’t need metaphors. It’s pretty simple.

The Spotify app should have a button that takes you to their website, where you can sign up for a premium subscription.

It doesn’t have one because Apple would kick Spotify out of the App Store.

Also - all other links to the Spotify website (support, terms of service, privacy policy, etc) take you to pages where the main navigation of the website has been removed so that you can’t find the signup page. Because again, Apple bans that. For the longest time apps have not allowed to have any way for users to find a signup form on a website.

That policy is now illegal in the EU (and a growing list of other countries) and Apple’s attempt at compliance is a new API - only available in Europe - that informs the user that they might be a victim of theft, fraud, etc before they get taken to a website that is deliberately sandboxed… supposedly to prevent theft/fraud/etc but more likely because it makes it really difficult for Spotify to link that signup with an existing free account.

Oh and if Spotify opts to expose users to see that horror show… they’d have to pay tens of millions of dollars per year to Apple. They have so far refused to do so, meaning the new regulations have failed (well, they were failing, until the EU declared Apple’s compliance efforts insufficient).

It just hasn’t hit that Twitter-level critical mass of users

Twitter used to be bigger than it is now and it also used to have less spam. So clearly size isn’t the problem.

The problem with twitter is Musk fired all the people who spent their day figuring out how to hide (or just delete) shitty content.