Removing the {{Draft}} macro

[wbamberg]

Some time ago we triaged KS macros in the JS to try to decide which ones we wanted to keep: mdn/yari#2846 (comment) .

Of the ones we wanted to remove it looks like only {{Draft}} is left. I have noticed people removing this here and there, but wonder if we have consensus to remove it all across the board.

Rationale:

• We shouldn't publish content on MDN that's not useful, so shouldn't use {{Draft}} to indicate that. We do have lots of incomplete content, only a small fraction of which is marked up with {{Draft}}. We should deal with this in the usual way by responding to issues and plan projects to fix it.

• On the other hand almost all content is draft in that it could potentially be improved or expanded, so {{Draft}} doesn't add anything.

• It's also not clear what use {{Draft}} is supposed to be for readers - if the content is incomplete that's obvious, if some of it is wrong it doesn't tell people which bits or how. Often {{Draft}} is left on a page long after it's already been made useful enough, so it only serves to make people anxious about the content, without giving them enough information to do something with that anxiety.

[teoli2003]

I'm 100% for removing {{Draft}}. If we have consensus, I'm for finding/replacing all occurrences and removing them and any mention of the macro in our meta documentation and plain deleting the macro.

With the PR system, non-ready documents don't get published. It is a remnant of the wiki era.

[wbamberg]

{{Draft}} was needed in the Wiki because there was no real way to write a first draft of something, get feedback and iterate, without publishing it. But now we are in GitHub that doesn't seem like a necessity.

The one page per PR worked because I am doing it solo, but if i wanted help building I would build out a template for all the interfaces of an API with “draft” so that others could add examples / descriptions based on a shell outline. If we don’t have some form of “under construction” we won’t be as able to group build.

I appreciate that having empty placeholder pages is one way to do this, but it's not the only way. Couldn't we coordinate large shared projects using a tracking issue?

I think it's better to separate the tools we have as writers from the experiences of people who are just reading the docs, and don't care about the internals, and as far as possible we should present people with finished pages. If it take some iterations to get there we can do that in review.

[hamishwillee]

I don't have a problem with Under Construction for that purpose - you're running a project and you need tools for that.

I also quite like the idea of using template placeholders for API reference with a "Please populate me" header - in many ways that is better than a 404 links as we have now.

What I don't like is the half way point as Draft is now - something that may or may not be finished, but generally there is no way to know what is expected of the reader.
I think we should clean up what there is now and then allow Draft or even better "under construction" but only for use as part of projects.

[hamishwillee]

I think it's better to separate the tools we have as writers from the experiences of people who are just reading the docs, and don't care about the internals, and as far as possible we should present people with finished pages. If it take some iterations to get there we can do that in review.

The rule that everything is expected to be good at the point of publish is very consistent, and simple for us as authors and reviewers to understand. Also good for readers - "this should be accurate" is a great simple rule.

That said, under construction headers or whatever have the benefit you can use them to encourage contribution. They also have value if BCD is complete, as the user gets the compat and spec data already.

[jpmedley]

I do think we need some form of “Under Construction” so people can build out an entire API and have placeholder pages with visitors knowing “this page is not yet built”.

If you can do it without affecting SEO. The cumulative affect of search results that don't contain useful information would not be good for the site.

[caugner]

FWIW As of today (2022-03-10), the macro is still used 14 times in content and 44 times in translated-content (I checked this in the context of mdn/yari#4943).

[estelle]

Still need to get the a11y roles merged... those are the last drafts.

[Rumyra]

I noticed when doing release notes this month that they were still in the FF rel notes (I removed them in new files I created) - now it's 5 on my count (all a11y) - so we're close!

[estelle]

I don't see {{Draft}} in my local code base. Can we 🎉 ?

[tannerdolby]

With #385 merged and the other separate PRs associated with {{Draft}} removal complete. I believe it is time to 🎉 !

[teoli2003]

In today's Yari, {{draft}}is definitively gone!