Docs: Add at least "In construction/WIP" pages for addons that are not documented to make these features more obvious

[AxiomeCG]

Description

I often miss great features that are present in the examples (the latest for me is NURBS) and are not:

1. documented (not a problem by itself here)
2. referenced in the documentation at least on a blank page/under construction that I could be seeing when searching in the search bar of the documentation.

Solution

I would be in favor of at least referencing the features present in the source code, even if they are not documented for two reasons:

1. it would allow devs to know that it exists when they browse the docs without needing to have a higher level of curiosity and search the repo everywhere for easter eggs.
2. it would also allow people to see that the documentation is missing, and to work towards making it available by contributing.

For point number 2, the people who will finally stumble upon the "hidden" feature in question, they will have to search in the source code how to use it, to understand how it works. If individually, we take this step of understanding, it would be great to go further and actually update the doc (that was a blank page) so that it is finally complete.

My point is to make it obvious and visible that we need contribution on this specific features.

Alternatives

It can be cool also to have some kind of metrics somewhere about the documentation coverage.

Additional context

This happened to me in multiple occasions:

• Marching cubes
• NURBS
• Water
• ...

As a beginner it could be tremendous to see what is actually "required" to know about when exploring what three.js has to offer. Even with a blank "Marching cubes" page, I would have wanted to know more about, and make my research aside. Then I plan to contribute to the documentation itself about this addon.

No response

[Mugen87]

Actually it is the primary purpose of the examples to demonstrate features of the library, not the documentation. All classes you have listed have a respective demo:

https://threejs.org/examples/#webgl_marchingcubes
https://threejs.org/examples/#webgl_geometry_nurbs
https://threejs.org/examples/#webgl_shaders_ocean

We have implemented a simple tags system some time ago, so you can search for certain terms like "water" and still find the webgl_shaders_ocean example. Or if you type "particles", you find "webgl_points_sprites", "webgl_points_dynamic" and many others.

So I could argue that you have just looked at the wrong place. Of course documenting everything would be better (like in every software project) but it is always a matter of time/budget to do this. And I'm not really a fan of stubs since they have to be maintained to certain degree as well and not necessarily create much value. TBH, I doubt it would help many users to discover features.

Besides, new exceptional features are always part of the release tweet by promoting them with screenshots.

[AxiomeCG]

If you ask me, examples are examples, not documentation.

In the case of the NURBSSurface, most of people I saw online in forum including myself have an hard time understanding the parameters.
For me, three.js should hide a part of the complexity of the understanding of the NURBS surfaces for instance. If it is to eat the math behind it in the wikipedia page, it is better for me to reimplement it myself.

Examples are sometime sufficient to some degree to take a grasp of the implementation, but it will never replace the parameters documentation with the actual constraints. knots1, knots2 for instance are arrays with numbers in the example, but what is the actual meaning that I should deduce from the numbers the example is given. Without becoming a NURBS expert, three.js is not helping me much here.

If not putting stubs, I think we need to find a way to make it more discoverable. Scrolling through the examples praying to see something that ressembles to what we want to craft is a bit erratic to me. By seeing the actual stub not documented, it would attract maybe people that knows the field or want to interest to the field, to document it for people that have not the academic background, or that are in a rush of implementing it.

Again, I speak about my experience struggling to find anything. At the beginning I was assuming that the documentation was containing everything that composes three.js to wake up one morning discovering that it is not that close.
I don't really know what we can make clearer in this context, it is why I wanted placeholder in the doc as a warning that there is much more than what is described in the documentation.

EDIT: I wanted to add that most of the automatic documentation tool that I used in the past like compodoc to parse the JSDoc, are creating pages even if the file is not documented, I find it useful to also count what is the % of documentation coverage left to do. This type of metrics is kind of useful to have a feedback also on how much work is left to do.

I will happy to contribute to the documentation either if you respond favorably to this issue. I want to make this documentation a better place :)

[Mugen87]

Examples are sometime sufficient to some degree to take a grasp of the implementation, but it will never replace the parameters documentation with the actual constraints. knots1, knots2 for instance are arrays with numbers in the example, but what is the actual meaning that I should deduce from the numbers the example is given. Without becoming a NURBS expert, three.js is not helping me much here.

I'm afraid you are asking for something that the documentation will never fulfill. At least in three.js the documentation should document the API, not explain the concepts behind it. You essentially asking for exactly that which is clearly out of scope.

For example the documentation for CubicBezierCurve states that the second and third parameter are control points. However, it does not explain what a control point actually is because somebody has to understand bezier curves first in oder to understand control points. But a technical documentation is not intended for supporting the dev in this context.

[AxiomeCG]

I'm not really in phase with what you are saying.

For Spherical, the documentation states a number of things that could vary from an implementation to another.

Imagine the same without the documentation, with just an example. You cannot invent what choices have been made in the implementation for the parameters, you need some priors. And just showing off a spherical would not have been enough.

For sure I'm not asking for a full explanation about NURBS in the documentation. But what are the constraints of the parameters for example is too much to ask, you think ?

"This value goes from 0 to 1" / "angle's space is between -PI and PI", this type of documentation is tremendously helping if you ask me. And it is a pretty common thing to do in a documentation. You need to make clear what are the preconditions and post conditions of the API.

For me three.js goal is to reduce the complexity through some abstraction. I'm maybe wrong about the assumptions I make.

At least I would have like a disclaimer of some kind on "How to abord the three.js documentation" stating that the documentation is incomplete and most of the magical stuffs are to be searched in the examples. It would have moderate my expectations. For the sake of the beginners, because it is not a usual way of abording a documentation if you ask me. (it is not a critic btw)

[Mugen87]

"This value goes from 0 to 1" / "angle's space is between -PI and PI", this type of documentation is tremendously helping if you ask me. And it is a pretty common thing to do in a documentation.

Stuff like units, value ranges etc. is of course fine. We just want to avoid to put too much information into the docs.

[AxiomeCG]

I don't want to make my case a generalization, but I thought for several months that the examples were just building on the foundation of what is described in the documentation. (maybe I'm just dumb)

I was amazed and disappointed at the same time that this is actually the tip of the iceberg. There are many things I could have saved myself from implementing if I had had the presence of mind to understand it in the first place. (is it a whim to ask for clarification?)

I don't know how many people share this frustration, which is why I opened this issue. Now what can I do to help three.js improve on this point. I don't have enough background yet to understand each examples and document the addons accordingly to flesh it out.

[braebo]

@0xAxiome it's not just you, the ThreeJS documentation is some of the most difficult docs I've ever had to work with, and reading through the examples can be cumbersome at best with the amount of (often questionably composed) boilerplate one needs to sift through in order to get to the parts of the (largely uncommented) relevant code. That being said, there is often enough information in there to slowly piece together the information one is looking for, it just takes orders of magnitude more time than it would with good docs.

I just want to push back a little on this statement:

We just want to avoid to put too much information into the docs.

The BabylonJS docs page for curves is a good example of the opposite side of the spectrum, with their examples used to compliment sections of the docs with in an interactive playground as opposed to being used as the docs. Their actual docs are separate from their API docs, and imo, API docs can almost never substitute real docs.

It's one thing to say "we don't have the resources for comprehensive documentation", and another to say that the current state of the documentation is ideal because "the documentation should [only] document the API". That's what typescript is for. My IDE documents the API without the need to context switch, and it doesn't replace the need for real, thorough documentation / examples.

That said, the ThreeJS project, to my knowledge, doesn't have a very large, very well funded team working on it around the clock like Babylon does. It's a rather small group of passionate open source devs with a much more limited scope. I think it's important to point out that while the ThreeJS docs are very far from ideal, they are certainly good enough to get by with some extra time and dedication, which is more than we can really ask for from such a small, dedicated team!

[AxiomeCG]

I agree with you @fractalhq on most of the points.

Moreover, I would want to really contribute to the documentation, but the guidelines about how to improve its discoverability is blurry to me. I'm really more about docs like the Babylon you shared.

We can maybe find a middle ground.

For me, each feature of three.js should have at least a WIP page with maybe the general sake of the module.
To make it discoverable, not just erratingly falling on by luck.

There is other problems to the documentation but it is not my point here in this issue.

But the time we think we spare not doing a "waterproof" documentation is the time we lose answering on discord channels, forums, stackoverflow... on very basic questions.

Really I would be happy to contribute, but we need a clear direction on where we want to bring the documentation.

For me, it is not a good thing to keep it "on surface", throwing a bunch of examples and if the planets are aligned, you may or may not find something, an ugly js code that you should examine very carefully to determine what in the world was the developer thinking while writing it.

Just so you know, I spent hours on the NURBSCurve, found a way to make it work a bit. I'm still not able to tell what is a knot1, knot2. The person who wrote the code of the example must know it somehow. The examples by essence are not enough.

[donmccurdy]

Their actual docs are separate from their API docs, and imo, API docs can almost never substitute real docs.

API references and tutorials are two distinct things, so let's not dismiss one or the other as not being "real docs" please. API references are a critical part of the three.js project, and we have to spend time on that (also see: i18n).

I understand you'd like three.js to have more long-form tutorials; so would I. Probably three.js Fundamentals or three.js Journey are more the format you're hoping for? Ultimately someone needs to write anything that is going to be added, but I think we're all broadly in favor of having more high-quality tutorials, in appropriate locations.

---

@Mugen87 I think I'm in favor of "stub" API references for things like THREE.Water and THREE.NURBS. Having links in the navigation going to a stub page does seem better to me than not having those links at all. And it may encourage others to contribute, if we request help on the stub pages. 😊

Those pages should remain API references, though. Any guides or tutorials can go in the appropriate sections.

[drcmda]

It is unusual that critical infrastructure is undocumented. Having to dig through raw source code to figure out how to use something, why treat JSM/EXAMPLES in this manner?

1. Make it its own repository free from core
2. Add a peer dependency range for three so that it is always tied to a working core
3. Each primitive has a markdown with a templated structure explaining technical details and the API, and one or more simple but focussed examples that should not contain boilerplate — at least it should require both to be present for new PR's
4. (This would finally allow Threejs to focus on core matters and go semantic semver with breaking, feature and fix releases)

I would also suggest that the new addons repo opens up to more contributors that can review, lead PR's through and fix bugs. similar to how three-types and three-stdlib is handled.

[AxiomeCG]

@drcmda I cannot agree more with what you said. You captured insanely well what is bothering me.

Making it a separate repository could be great. The semver is also a huge topic. (In addition to the fact that backward compatibility is not a known characteristic of three.js)

A clear documentation, (even with some of the pages in construction with a message inviting to contribute maybe), that would point also new features with a little tag "New" like we can see in design systems.

This deep understanding of what exist and what does not, bringing the community to a better understanding, could lead to more contribution and less pollution in terms of forums and stuffs.

[Mugen87]

I think I'm in favor of "stub" API references for things like THREE.Water and THREE.NURBS. Having links in the navigation going to a stub page does seem better to me than not having those links at all. And it may encourage others to contribute, if we request help on the stub pages. 😊

I've changed my mind and agree now that having stub pages is better than nothing. Let's use #27034 to track the addition of these pages.