Helping you get started with new API references

[jpmedley]

Gang,

Writing new API reference requires a bit of set up. Folders and files need to be created in a specific structure. Standard headings and metadata need to be filled in.

To remove friction from this process, I've created a repo that contains a bunch of boilerplates for content that doesn't exist. All you need to do is:

1. Create a new branch in your clone of mdn/content.
2. In the boilerplates repo, locate the folder for the API you want to document.
3. Copy it or download it to your new mdn/content branch.
4. Add text and examples to the boilerplates.
5. Commit your new content and submit a pull request as normal.

If the API you want to document is missing from the repo, contact jmedley@google.com.

If you have reason to think someone else might want to work on a feature, use this process. Otherwise have at it. (I'm looking for the simplest, least bureaucratic way to prevent duplication of error. Let me know if you have an idea.)

[hamishwillee]

I was thinking of creating a yari template wizard to make things like this "generically". This is at least as good and possibly better. Does your generator know about method prototypes so that the syntax blocks can be auto expanded out?

On spot check, the syntax does not quite match what we're doing now for JavaScript: DOMStringList.contains() would be contains().

[jpmedley]

I had to write some new code. I'm resolving the last bugs and hope to have updated reference pages uploaded later today.

[jpmedley]

Reference pages are now pre-populated with methods, parameters, and events. I plan to do something similar with method arguments, but I don't have an ETA.

[hamishwillee]

Nice! I think that saves a bit of time - examples https://github.com/jpmedley/mdn-boilerplates/blob/main/api/domfilesystem/index.md and https://github.com/jpmedley/mdn-boilerplates/blob/main/api/animationeffecttimingreadonly/index.md

Something weird going on here: https://github.com/jpmedley/mdn-boilerplates/blob/main/api/canvascapturemediastreamtrack/index.md#syntax

There was a discussion somewhere about generating this sort of thing from Yari. FYI I pointed here.

[jpmedley]

Something weird going on here:

There's a typo in the IDL. Look for a fix in the next push.

There was a discussion somewhere about generating this sort of thing from Yari. FYI I pointed here.

Any possibility you could focus on CSS? What I've done so far is not trivial. I've been trying to get to CSS for 3 years, but can't find the time.

[hamishwillee]

Any possibility you could focus on CSS?

Unfortunately not. I'm weak on CSS and only do that when the rest of the team runs out of bandwidth. i.e. I don't think I'd add much value.