Useless documentation

[ghost]

There is no documentation for web developers on how to use the standard, and the examples for web developers in the specification are meaningless.

I suggest two things, either create documentation for web developers such as tutorials or improve the examples for web developers in the specification so that web developers can make sense of it, or cease development and stop wasting your life working on a standard that will never come because web developers don't know how to use it.

[ghost]

The audience for the specification is software developers, not web developers. Web developer examples shouldn't even be in the specification. There should be documentation for web developers that is separate which covers how to use the standard.

[arhadthedev]

This is because any web standard is written not for web developers who need to understand the technology, but for browser creators only. In other words, it does not educate step by step how to use things, but specifies instead how exactly these things must work and be built. That's why is has lots of mundane technical details and lots of clutter - just to make browsers ticking precisely.

For developer oriented tutorials that really untangle all of this stuff, there are third party sites really dedicated to it, like MDN (https://developer.mozilla.org/) and extremely vast step by step tutorials googlable by queries like css tutorial.

However, I absolutely agree that in-specification examples "for web developers" can be used only to recall small details and have no use for these who meet it in the first time and need context where specification bits may be used. In other words, the XXX specification requires already existing background and experience in XXX to correctly understand what happens in the specification.

[arhadthedev]

For any maintainer passing by: for readers of the DOM specification who has no grasp in DOM, current non-normative snippets really do not establish context where methods and properties may be used. So it would be great to supply each non-normative paragraph with small, unit test like explanatory examples with assertions.

[ghost]

Yes, the specification should be for web browser developers, but the DOM specification has sections for web developers as well, and the information in the web developers sections are absolutely useless to web developers.

Yeah, I know there are third party resources but I only learn from authoritative sources, or I don't use the technology at all.

DOM needs web developer document with the browser developer document, like HTML:

Documentation for browser developers: https://html.spec.whatwg.org/multipage/

Documentation for web developers: https://html.spec.whatwg.org/dev/

DOM also needs a code validator so people can also confirm that they have used DOM correctly..

To me, DOM is a complete failure. I hope the powers that be get their shit together in the next version and create a usable product. I would like to use it.

[marcoscaceres]

That authoritative source for web developers is MDN. The standards community works closely with the technical writers of MDN to make sure the content at MDN is authoritative (as far as web developer need it to be):

https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model