I want to know that all JS pages are tagged to their corresponding recipe in stumptown, so I can get complete results for the linting that will come out of #2784.
scraper-ng identifies one and only one recipe for every JS pageRetitled in response to https://github.com/mdn/sprints/issues/2784#issuecomment-582889192.
Looked at the linter output for this and here's a checklist to burn down for some tagging party.
Non-unique recipes:
Missing recipe:
@Elchi3 Thank you so much for doing this! π―
I've fixed the "file-require-recipe-unique" ones. They are mostly because of error pages like ReferenceError() containing an "Error" tag. I wasn't sure whether we ought to remove them or choose something different to flag "javascript-error" recipes. But I decided to go for it in the end. But let me know if you think this was a bad choice, we can always reinstate.
I've tagged many more pages. The "funny" thing is that I'm now discovering pages I've never seen before. :neutral_face:
Some random thoughts for the remaining pages. Would love some feedback, so I feel more empowered to take some decisions :)
@chrisdavidmills What was the comment on the Microsoft docs in the PAB meeting? Do we need to start supporting this material in our stumptown efforts?
I'm not sure what to do with the "New in JS" pages. It's historical information. Maybe it should move to the archive?
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/DateTimeFormat_Options this is brand new. Someone created this. In APIs this would be a dictionary, I guess. I don't think I want to support this content type in JS docs, though. Not a fan of isolated dictionary docs.
If we remove the index page from jsSidebar, then I guess we could delete the index page.
What was the comment on the Microsoft docs in the PAB meeting? Do we need to start supporting this material in our stumptown efforts?
Unfortunately this was one of the topics that was postponed because we ran out of time. I'll start a thread with the PAB folks now, to see if I can get any kind of resolution.
I'm not sure what to do with the "New in JS" pages. It's historical information. Maybe it should move to the archive?
I know I'm not a decision maker on this, but I hope we delete or archive this stuff. All but one of those pages concerns changes that landed nearly a decade ago. I imagine BCD or browser release notes are going to be more meaningful for this sort of thing anyway.
If we remove the index page from jsSidebar, then I guess we could delete the index page.
I thought DocStatus used the index page: https://github.com/mdn/kumascript/blob/master/macros/DocStatus.ejs#L44 ? For the same reason I've been thinking that we can't remove the {{Index}} macro: https://github.com/mdn/sprints/issues/2524#issuecomment-593704900.
I've taken notes on the pages that still need handling. There's some new stuff here, but there's a little bit of recap too. I've tried to highlight new proposals that I'm making.
Proposal: Delete this page.
I can't figure out where this inherit() method comes from or I would've suggested moving to the method page's examples. But the sample code doesn't run anyway, so I say dump the page outright.
Discussed above. Seems like we're stuck with this one, for now. No action.
Discussed above.
Proposal: fold this content into the parent DateTimeFormat page.
Proposal: fold into the examples section of defineProperty.
I've tagged this as a guide page.
Proposal: correct me if I'm wrong. π
I guess this is a guide page, but if we ignore it long enough, it'll become historical and irrelevant. π Open to ideas on this one.
I'm tagging these as language features, since these hew closely to the recipes already.
Proposal: correct me if I'm wrong. π
And it's children. Discussed above. We're waiting to hear from the PAB before we can act on these.
And it's children. Discussed above. I think we need @chrisdavidmills for consensus on archiving or deleting.
This is a draft page, and one that hasn't been edited in nearly a year. I'd say that's abandoned, really. But I'm wondering if we ought to detect draft pages in the linter and demote all messages about them to warnings.
Proposal: Ignore or delete.
One thing to consider is how far we want to fix the content for its own sake, and how far we just want to make it scrapable, and worry about fixing it afterwards. For example, in some of these cases (like the "New in JS") the simplest thing is just tag them as guide pages. That avoids having conversations about "is this content really deletable". Treating pages as guide pages only becomes impossible when they have special custom content (like interactive examples) that guide pages don't support.
I'm not exactly saying we should do the minimum needed to make the content scrapable, but I am worried that once you start down the road of "fix the content on the way", then there's so much extra work in there, and I'm not sure where you stop.
- https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null
- https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined
I'm tagging these as language features, since these hew closely to the recipes already.
Proposal: correct me if I'm wrong. π
That sounds plausible to me. From what I can tell from the spec, they are the only values of the Null and Undefined types. So they're not "global objects". Should we also then move them out of "Global_Objects"? For things like the sidebar, we are implicitly assuming that all the things in /Global_Objects are actually "javascript-class" pages.
I'm wondering if we ought to detect draft pages in the linter and demote all messages about them to warnings.
I'm not sure about this. For one thing we are also planning to remove {{Draft}}. For another thing though: draft pages that are unscrapable still have to be dealt with, either by deleting them or fixing them.
I'm not sure about this. For one thing we are also planning to remove {{Draft}}. For another thing though: draft pages that are unscrapable still have to be dealt with, either by deleting them or fixing them.
One thing I proposed as part of my localization plan (the part about reducing the amount of content) was simply scrapping anything in draft that had bene in draft for any significant length of time, unless it really looks like content is valuable, in which case we should sort it out (maybe file a sprint P1 bug for it?)
One thing to consider is how far we want to fix the content for its own sake, and how far we just want to make it scrapable, and worry about fixing it afterwards.
This is a good point, but I'm still supportive of deletions, at least. It's less content to scrape and odds are good that it improves the corpus as a whole. I agree that fixes like combining pages is not essential to the overall scraping effort.
Items like 97. https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty/Additional_examples are complicated, though. If they were part of a non-guide page, then we could scrape them as examples. As a guide page, they're just dumb code blocks.
I thought DocStatus used the index page: https://github.com/mdn/kumascript/blob/master/macros/DocStatus.ejs#L44 ? For the same reason I've been thinking that we can't remove the {{Index}} macro: #2524 (comment).
I forgot about this. Thanks. Well, I think we could remove it from doc status and from the sidebar and then delete it. I think doc status pages shouldn't make it to github anyway.
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Differential_inheritance_in_JavaScript Proposal: Delete this page.
Deleted.
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/DateTimeFormat_Options Proposal: fold this content into the parent DateTimeFormat page.
Done. Redirected to constructor page which documents this.
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty/Additional_examples Proposal: fold into the examples section of defineProperty.
Deleted. These examples were seriously old and the binary flag implementation of the method is like these little libraries that shouldn't be hosted on MDN at all.
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/Planned_changes I guess this is a guide page, but if we ignore it long enough, it'll become historical and irrelevant. see_no_evil Open to ideas on this one.
Yeah, Guide page now. This will be old in a year and then we can archive it.
https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/The_performance_hazards_of__%5B%5BPrototype%5D%5D_mutation This is a draft page, and one that hasn't been edited in nearly a year. I'd say that's abandoned, really. But I'm wondering if we ought to detect draft pages in the linter and demote all messages about them to warnings. Proposal: Ignore or delete.
Marked as Guide page for now. I searched for this and it seems to be relevant on stackoverflow and other sites, so we should finish this page one day.
null / undefined
Should we also then move them out of "Global_Objects"? For things like the sidebar, we are implicitly assuming that all the things in /Global_Objects are actually "javascript-class" pages.
Yeah, probably. I think this needs some sorting, but I assume we should split this out of this issue. Too much work to get into that now.
I think what is left here (or to be done as follow-ups) is:
Other follow-ups: Some pages like null and undefined should probably be moved around (also the Intl namespace, we have an issue for this). But I assume that work is out of scope for the moment, it will come back when we fix pages to comply with their recipes. Does that make sense?
@Elchi3 Thank you! I think opening follow up issues for these tasks and resolving this user story is the way to go. I'm not exactly quite sure how to write them or organize them though. Are they user stories of their own? What's the categorization of minor tasks like this?
Are they user stories of their own? What's the categorization of minor tasks like this?
I just filed https://github.com/mdn/kumascript/pull/1340 to update the sidebar.
I would suggest we file another story for the MS docs. If we wanted to, we could just tag those docs, for the sake of completing this story. I mean, it's fairly obvious what https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Microsoft_Extensions/at-if should be tagged as. It'll fail the linter, of course, but that's separate to this story.
I think "remove index from... doc status" is tricky. DocStatus is very dependent on Index, so much so that removing Index essentially means retiring DocStatus for the JS pages.
I think doc status pages shouldn't make it to github anyway.
I agree with this, but I thought doc status was still an important tool for localizers, while we are in Kuma.
If we wanted to, we could just tag those docs, for the sake of completing this story. I mean, it's fairly obvious
This is a good point. I've gone ahead and done this. That leaves only Index and the "New in JS" pages untagged. I supposed the "New" pages could also be tagged as guides, but it seems like the path to archiving them is pretty straight forward.
Awesome, I think we might get this done in time then. I agree on the MS docs tagging. It would be nice to hear if we need to further worry about these or not, though. Let's hope we'll get an answer.
Thanks for the sidebar PR, I have a question on that one, but good to go. If this is deployed, I will move the "New in JS" pages to the archive.
I'm tagging the Index page as "Guide", because Will is probably right, that it needs to stay for the moment.
Attempt to remove index from doc status https://github.com/mdn/kumascript/pull/1341
The JsSidebar updates from https://github.com/mdn/kumascript/pull/1340 are merged, deployed, and Ryan has rendered the pages: https://github.com/mdn/kuma/issues/6677
The changes to DocStatus are merged and deployed: https://wiki.developer.mozilla.org/en-US/docs/MDN/Doc_status/JavaScript
So I think we can archive "New in..." and delete the Index page, and then close this?
So I think we can archive "New in..." and delete the Index page, and then close this?
This is correct, though it'd probably be a good idea to open an issue for deciding on what to do with the Microsoft Extensions pages (though I'm not exactly sure what the issue should say β it's hard to formulate as a user story). That's not a blocker to completing _this_ user story, but it seems like a good idea to track that work somewhere.
Also, I would archive the "New inβ¦" pages, but I don't know how to do that. A pointer to instructions for that would be appreciated (assuming it's less work to tell me how to do it than to just do it).
what to do with the Microsoft Extensions pages
As an FYI - I asked the PAB crowd what they think about removing the MS-specific stuff, and they generally said it sounded reasonable, although we should probably look at the kind of usage figures the pages have, and see if anyone is going to miss them.
Funnily enough, we got no response at all from the MS reps.
I had a look at the usage figures on GA, and a few of the pages (like ActiveXObject) have a few thousand views per month. But most have very little. I guess the problem here is that it'd be a lot of work to get them updated to start passing linting against the page recipes, for very little gain.
What I think we should do is treat them in the same way as Mozilla/ and Archive/ pages - don't bother to fix them up or aim to get them into structured data, just dump them in the archive so they still exist if someone needs them.
So I think we can archive "New in..." and delete the Index page, and then close this?
I moved the "new in" pages and I deleted the index page.
What I think we should do is treat them in the same way as Mozilla/ and Archive/ pages - don't bother to fix them up or aim to get them into structured data, just dump them in the archive so they still exist if someone needs them.
I agree with this and would go forward with moving them to archive if that has consensus with Will and Daniel.
@chrisdavidmills thank you for asking the PAB!
@Elchi3 Moving to the archive works for me. π And thanks for moving the "New inβ¦" pages.
I just ran the linter and got:
Macro: jsxref 7393 warnings jsxref
Macro: JSRef 677 warnings jsref
Macro: JsSidebar 233 warnings jssidebar
Macro: optional_inline 200 warnings optional_inline
Macro: Glossary 151 warnings glossary
Missing from javascript-method: prose.description 143 errors javascript-method/prose.description
Linting data.info_box ingredient is unimplemented 110 warnings javascript-property/data.info_box
Missing from javascript-error: prose.short_description 73 errors javascript-error/prose.short_description
Missing from javascript-constructor: prose.description 63 errors javascript-constructor/prose.description
Macro: ReadOnlyInline 61 warnings readonlyinline
Missing from javascript-method: data.specifications 50 errors javascript-method/data.specifications
Macro: js_property_attributes 49 warnings js_property_attributes
Missing from javascript-method: data.examples 49 errors javascript-method/data.examples
Macro: bug 43 warnings bug
Macro: Non-standard_Header 43 warnings non-standard_header
Linting data.class_constructor ingredient is unimplemented 35 warnings javascript-class/data.class_constructor
Macro: PreviousNext 32 warnings previousnext
Expected SpecName macro for javascript-method: data.specifications 28 errors javascript-method/data.specifications/expected-macro
Macro: Obsolete_Header 26 warnings obsolete_header
Missing from javascript-language-feature: data.examples 24 errors javascript-language-feature/data.examples
Missing from javascript-property: data.specifications 24 errors javascript-property/data.specifications
Macro: deprecated_header 23 warnings deprecated_header
Missing from javascript-method: data.browser_compatibility 23 errors javascript-method/data.browser_compatibility
Missing from javascript-property: prose.description 22 errors javascript-property/prose.description
Expected h2#Specifications 22 errors javascript-method/data.specifications/expected-heading
Expected h2#Browser_compatibility 22 errors javascript-method/data.browser_compatibility/expected-heading
Missing from javascript-constructor: prose.syntax 20 errors javascript-constructor/prose.syntax
Missing from javascript-language-feature: prose.description 19 errors javascript-language-feature/prose.description
Missing from javascript-constructor: data.examples 19 errors javascript-constructor/data.examples
Expected SpecName macro for javascript-property: data.specifications 17 errors javascript-property/data.specifications/expected-macro
Missing from javascript-property: data.examples 17 errors javascript-property/data.examples
Missing from javascript-language-feature: data.specifications 14 errors javascript-language-feature/data.specifications
Missing from javascript-class: data.examples 11 errors javascript-class/data.examples
Macro: EmbedTest262ReportResultsTable 10 warnings embedtest262reportresultstable
Missing from javascript-error: prose.message 9 errors javascript-error/prose.message
Missing from javascript-error: prose.error_type 9 errors javascript-error/prose.error_type
Missing from javascript-error: prose.what_went_wrong 9 errors javascript-error/prose.what_went_wrong
Missing from javascript-method: prose.see_also 9 errors javascript-method/prose.see_also
Macro: DOMxRef 8 warnings domxref
Missing from javascript-language-feature: prose.syntax 8 errors javascript-language-feature/prose.syntax
Missing from javascript-property: prose.see_also 8 errors javascript-property/prose.see_also
Linting prose.overview ingredient is unimplemented 7 warnings landing-page/prose.overview
Linting data.link_lists ingredient is unimplemented 7 warnings landing-page/data.link_lists
Expected SpecName macro for javascript-language-feature: data.specifications 7 errors javascript-language-feature/data.specifications/expected-macro
Expected h2#Specifications 7 errors javascript-language-feature/data.specifications/expected-heading
Missing from javascript-class: data.specifications 7 errors javascript-class/data.specifications
Expected h2#Specifications 7 errors javascript-property/data.specifications/expected-heading
Missing from javascript-namespace: data.examples 6 errors javascript-namespace/data.examples
Expected h2#Browser_compatibility 6 errors javascript-property/data.browser_compatibility/expected-heading
Missing from javascript-property: data.browser_compatibility 6 errors javascript-property/data.browser_compatibility
Missing from javascript-language-feature: data.browser_compatibility 5 errors javascript-language-feature/data.browser_compatibility
Expected h2#Browser_compatibility 4 errors javascript-language-feature/data.browser_compatibility/expected-heading
Macro: Draft 4 warnings draft
Expected SpecName macro for javascript-class: data.specifications 4 errors javascript-class/data.specifications/expected-macro
Missing from javascript-class: data.browser_compatibility 4 errors javascript-class/data.browser_compatibility
Macro: EmbedLiveSample 3 warnings embedlivesample
Missing from javascript-language-feature: prose.see_also 3 errors javascript-language-feature/prose.see_also
Macro: SeeCompatTable 3 warnings seecompattable
Expected h2#Specifications 3 errors javascript-class/data.specifications/expected-heading
Expected h2#Browser_compatibility 3 errors javascript-class/data.browser_compatibility/expected-heading
Macro: Previous 2 warnings previous
Missing from javascript-class: prose.see_also 2 errors javascript-class/prose.see_also
Expected SpecName macro for javascript-constructor: data.specifications 2 errors javascript-constructor/data.specifications/expected-macro
Missing from javascript-constructor: data.specifications 2 errors javascript-constructor/data.specifications
Macro: Next 1 warning next
Macro: ListSubPages 1 warning listsubpages
Missing from javascript-constructor: prose.see_also 1 error javascript-constructor/prose.see_also
Missing from javascript-error: data.examples 1 error javascript-error/data.examples
Missing from javascript-method: prose.short_description 1 error javascript-method/prose.short_description
Missing from javascript-constructor: prose.short_description 1 error javascript-constructor/prose.short_description
Expected h2#Specifications 1 error javascript-namespace/data.specifications/expected-heading
Missing from javascript-namespace: data.specifications 1 error javascript-namespace/data.specifications
Expected h2#Browser_compatibility 1 error javascript-namespace/data.browser_compatibility/expected-heading
Missing from javascript-namespace: data.browser_compatibility 1 error javascript-namespace/data.browser_compatibility
Missing from javascript-method: prose.syntax 1 error javascript-method/prose.syntax
Missing from javascript-property: prose.short_description 1 error javascript-property/prose.short_description
-> 0 recipe errors, so I think we can close this issue.
What I think we should do is treat them in the same way as Mozilla/ and Archive/ pages - don't bother to fix them up or aim to get them into structured data, just dump them in the archive so they still exist if someone needs them.
I agree with this and would go forward with moving them to archive if that has consensus with Will and Daniel.
I'm fine with this, but I don't really have any particular authority to decide what to do with these pages. An alternative, if we want to keep them in /JavaScript, is to tag them as guide pages, which I think would work OK (they don't contain any exciting macros we'd need to worry about, although they do use things like <dl> which would be a little, um, modified in the transition).
I guess the problem here is that it'd be a lot of work to get them updated to start passing linting against the page recipes
Yes. Things like, we'd have to write BCD for them all, and examples, and rewrite the structures...
An alternative, if we want to keep them in /JavaScript, is to tag them as guide pages, which I think would work OK
Wouldn't that be a bit of a hack though? It seems wrong to start hacking stumptown this early on in the process ;-) I like the idea of doing it properly, or not at all. If we were to put them in the archive, they would still be available, and redirects would make sure that any links in place won't break?
Wouldn't that be a bit of a hack though? It seems wrong to start hacking stumptown this early on in the process
We talked a little about this risk when we were in London. It's pretty unrealistic to expect that we'd be able to clean up and structure everything coming into Stumptown. The guide pages are the shallowest of shallow structure, so I don't think this is a hack, so much as admission that we're going to have to drag some legacy content along or rely on the community to help us do some cleanup _in_ Stumptown.
I don't think this is a hack, so much as admission that we're going to have to drag some legacy content along or rely on the community to help us do some cleanup in Stumptown.
OK, WFM. Thanks for the explanation!
Most helpful comment
I just ran the linter and got:
-> 0 recipe errors, so I think we can close this issue.