Using macro calls for future non existing pages

[OnkarRuikar]

It has been seen that new page authors are putting macro calls to non existing future documents: {{domxref("to-be-written-page")}}. Some times the future pages are not written and these macro calls add to flaws. Also, the links appear red on the rendered page.

For example, on https://developer.mozilla.org/en-US/docs/Web/API/Navigator page usage of {{domxref("Navigator.standalone")}} leads to the following flaw:

MacroBrokenLinkError from domxref line 178:7
Explanation: /en-US/docs/Web/API/Navigator/standalone does not exist

Pros of such practice:

1. Authors break huge PRs in multiple small PRs. In such case they use such speculative macro calls. Once all the PRs are merged they don't have to revisit same pages to add the links.
2. Someone made argument that this could be used as some sort of TODO reminder about unimplemented pages.

Cons of such practice:

1. If the pages are not written then these speculative macro calls remain as broken links which looks bad on rendered pages.
2. Due to such practice repo maintainers ignore all broken link flaws while merging the PRs. Thus defeating the purpose of PR companion.
3. We are close to getting flaw count to zero only 500+ flaws left. It would be great if we avoid such practice to keep flaw count to zero all the time. This will help us telling maintainers to take flaws seriously and not to merge PRs with flaws.

Solution

a. 🎉 Keep using the practice. And in PR companion workflow make changes to not report these flaws in PR comments. Sweep these under the rug. But the down side is that we won't know about genuinely broken links due to typos. If one wants to really see and fix these flaws then they will have to run full build in local dev environment and see the flaw dashboard.
b. 🚀 Ask authors not to use such macro calls. They could merge all the PRs, except the last one, without the macro calls and merge the last one with all the links placed in pages in previous PRs. This could be bit painful.

What are your thoughts? which solution do you prefer? To vote add reaction on this post. For solution a use 🎉 and for b use 🚀 .

---

The same argument could be made for the front-matter key browser-compat. People use speculative BCD queries in new pages and then they don't create PR to put compat table in BCD repo.

For example on page https://developer.mozilla.org/en-US/docs/Web/API/AudioParamDescriptor BCD query api.AudioParamDescriptor has been used which leads to the following flaw:

No BCD data for query: api.AudioParamDescriptor

[OnkarRuikar]

I prefer solution a as it is convenient for authors and we've been ignoring these flaws for a long time anyways. Also there will be no friction between authors and reviewers about the small broken link issues. I could update the PR companion workflow to sweep these flaws under the rug and we can be strict about the other flaws.

[Josh-Cena]

I very much prefer TODO macros. If we worry about broken links, we can add a macro parameter representing "don't report it, it will be written", and generate a flaw if the target link actually exists. It's much easier to batch-create links while you are writing docs for an entire area, than to retroactively add links when writing one or two singular pages, as the relationship between APIs is much clearer in the first case.

[bsmth]

I like this idea with a placeholder parameter, especially if it means we don't render a broken <a> in the content but use some other HTML to represent it.

[OnkarRuikar]

a macro parameter representing "don't report it, it will be written"

This sounds cool but it will be hard to implement as there are already optional parameters in the macros. The new parameter will have to be a non boolean value, like {{domxref("ABCInterface", "todo=true")}} or {{domxref("api.ABCInterface", "ABCInterface", "todo=true")}}. So that in macro code we could compare the param value to the string.

Also as these calls won't be reported as flaws, it'll be hard to track these if the param is a boolean. With todo=true string we can also do todo=true string search on content files to get list of TODO docs.

We'll have to rope engineering team in about how to get this done.

if it means we don't render a broken in the content but use some other HTML to represent it.

Another good idea! For todo=true links we can simply render api.ABC in inline code block, without the current red anchor broken link style. So in future if we see red broken link on a page then we can simply edit the page and make it not link.

[Josh-Cena]

+1 for "todo=true" or just "todo"

[OnkarRuikar]

"todo"

todo could mistakenly get identified as feature/API name.

[Josh-Cena]

To be clear it would look like {{domxref("ABCInterface", "ABCInterface", "todo=true")}}. There's absolutely no way that "todo=true" as the second parameter won't be ambiguous.