MDN Web Docs
Replies: 2 comments 9 replies
-
|
I don't have a problem with mixing interfaces if it helps, but I am not certain it is a silver bullet. If you mix all the APIs there are lots of irrelevant interfaces for each of the current APIs and you still only get The big problem here is I don't see how we can do this "right" - except perhaps with some infrastucture that allows "sub APIs" so we could display all three APIs in the sidebar at the same time as separate APIs. Can we prototype just dumping everything in one "Authentication API" and seeing how navigable it is to do it this way? Notes:
|
Beta Was this translation helpful? Give feedback.
-
|
I'm not exactly advocating for this, and I'm not sure it's the right thing to do, but ...
A "sea of interfaces" seems like a bit of a loaded expression for not that many interfaces - if you amalgamate the four APIs you get 15 interfaces which is a very small sea, more of a large puddle. What you do get though, is all the credential types appearing together in a single list, which helps reinforce the core idea that the CM API works with a variety of different credential types. Look at the sidebar for WebOTP: 
It has only two items in it. The key one is CredentialsContainer.get(). If I click that, I get a totally different sidebar, with no link to I do, however, see links to
I'm not sure how that helps though. Who cares about "APIs", where "API" really means "spec"? Why does it matter to any web developer that FedCM is a different spec from CM? There are absolutely irreducible problems with these APIs, mainly things like "don't use the thing called
Combining CM, WebAuthn, WebOTP, and FedCM would get a sidebar that looks like this: 
I would add a couple of overview guides and try to homogenise the names of the existing guides, to present it as a unified whole.
Yes, same for FedCM. Similarly only |
Beta Was this translation helpful? Give feedback.
-
|
FWIW I think that is a bit of a "sea of interfaces" if you're only interested in OTP. But you're mis-interpreting me - it was a genuine question "is this better?" I did the same experiment with looking at OTP and navigating too and that is rubbish. On balance I think it is better. BTW, would be nice to spell out OTP at least once as "one time password". It is a bit annoying that you lose guides if you go to an interface. If I was looking at one of these docs to work out what are the relevant interfaces for what I want to do, it would be good to easily be able to go back to the "relevant list". That's what the sidebar is supposed to do for you, and if you have just one related feature set it does. |
Beta Was this translation helpful? Give feedback.
-
Very annoying, indeed -> mdn/yari#6229. |
Beta Was this translation helpful? Give feedback.
-
|
Having read through this discussion, I will start by saying that I appreciate the effort here in trying to improve this situation. I tried documenting FedCM, and WebOTP, and making improvements to WebAuthn, using the normal strategy we tend to use in documenting APIs. But it didn't work particularly well because of the weird footprint of these APIs. A few thoughts:
|
Beta Was this translation helpful? Give feedback.
-
|
Woo hoo! |
Beta Was this translation helpful? Give feedback.
-
|
Thanks @hamishwillee and @chrisdavidmills for your thoughts both, they are greatly appreciated. I agree with just about everything Chris has in https://github.com/orgs/mdn/discussions/683#discussioncomment-9517279. I'm going to do this piecemeal, trying to improve what's already there before trying to move things around. I think "Authentication API" makes sense? Names are hard :). So next up I think is:
Then after that consider amalgamating the APIs, and writing/reshaping various guide pages. |
Beta Was this translation helpful? Give feedback.
-
|
Yes, that all works for me :-). I'd do |
Beta Was this translation helpful? Give feedback.
-
|
Sounds perfect Will. |
Beta Was this translation helpful? Give feedback.
-
|
Sorry for just getting around to reading this - I also agree with what @chrisdavidmills says :) If we separate this into two problems: 1. sidebars reflecting related docs & 2. organising docs to make sense I see a future where
|
Beta Was this translation helpful? Give feedback.
-
I'm doing some work on the Credential Management API and had a suggestion.
The CM API provides a kind of framework that several other specifications plug into:
Usually our practice on MDN is to document separate specifications separately, and that's what we've done here.
But in some cases, including arguably this one, it can lead to fragmentary docs in which it's hard for readers to get an overview of what's going on. For example:
create()andget()methods are defined in the CM API, so their sidebars list the objects defined in the CM API. These methods return a subclass ofCredential, but most of those subclasses are not listed in the sidebar, because they're defined in different specs.createandgetwould like to talk about all the credential types (e.g. WebOTP codes, WebAuth assertions, etc) that can be used with them, but is then straying into documentation belonging to the other specifications.createandget, but those belong in the CM API tree. The documentation for https://developer.mozilla.org/en-US/docs/Web/API/WebOTP_API looks pretty stunted and a little incoherent because it's missing the context provided by the CM API docs.So we could consider instead folding all the other specs into the CM API documentation. The obvious precedent for this is the Performance documentation, where there are many tiny specs that extend the core Performance stuff, and that we all rolled up together last year when @Elchi3 did the rewrite.
Beta Was this translation helpful? Give feedback.
All reactions