How to document inherited interfaces without duplication

[bsmth]

Hi all,

We had a short chat about this one already, but with the hopes that we come out the other side with clear approach / gameplan in future when we see cases like this, I'm going to start a short discussion. I'm in the middle of documenting OffscreenCanvasRenderingContext2D which has 44 methods and 27 properties, most of which are inherited from CanvasRenderingContext2D.

There are two options:

1. Refer to the methods and properties of 'the parent' (2 .md files added, 8 modified):
   11591 OffscreenCanvasRenderingContext2D content#20089

2. Add new pages for each of the inherited methods and properties (64 .md files added, 13 modified):
   11591 OffscreenCanvasRenderingContext2D with duplicated pages content#20090

Please leave some feedback on what should be done here to ensure that we have comprehensive docs, but do not add too much maintenance overhead.

[Elchi3]

(I don't know yet which option is best, still thinking about it.)

However, I want to leave an example here to show that it isn't necessarily duplicated pages. I was in a similar situation when I was "demixing" many docs on MDN. The example is ChildNode. I did the work to document the members of this mixin on the specific objects. It meant creating 3 pages instead of one. Here they are:

• https://developer.mozilla.org/en-US/docs/Web/API/Element/after
• https://developer.mozilla.org/en-US/docs/Web/API/CharacterData/after
• https://developer.mozilla.org/en-US/docs/Web/API/DocumentType/after
  (same for before, remove, and replaceWith, each documented 3 times instead of once)

See how the pages are different (especially the code examples). Of course, this mixin is small (4 methods, and not 44). The compat table is often different, too. It would certainly be the case here.

So, questions to ask are maybe: How different are canvas members really depending on the context? Is there different code to show to readers? Are there things to watch out for only on offscreen? Where would that be documented?

If it is really identical 99% of the cases, then "duplication" isn't needed, I guess.

[hamishwillee]

So, questions to ask are maybe: How different are canvas members really depending on the context? Is there different code to show to readers? Are there things to watch out for only on offscreen? Where would that be documented?

I still don't know how different they are. @bsmth the 2 PRs don't show cases that allow you to know this. COuld you show https://pr20090.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/OffscreenCanvasRenderingContext2D/arc both ways - ie as a combined doc and as a separate one?

I still lean towards separate docs. We de-mixed for a reason.

[bsmth]

There's really no difference with how the methods and params work when it's a regular canvas context and and offscreen canvas context:

https://codepen.io/bsmth/pen/ExEBJYE

arc(), for instance, requires no special handling whether used on regular canvas context or offscreen.

[hamishwillee]

Then it's really down to whether we can live with the sidebar being a bit crap.

[Josh-Cena]

Chiming in to mention mdn/content#20019 (and possibly mdn/content#20025, https://github.com/mdn/content/discussions/18002)

It really depends on how much the duplication is. I'm strongly leaning towards deduplicate where possible, but I expect a lot of disagreement so just my 2 cents.

[bsmth]

Thanks all for the input, I'm going to proceed with not duplicating the method & properties pages in this case. I'll close the other draft PR and have a go at pointing out differences with the mixin only. 🙌🏻