Documentation of Skinned Meshes is unclear

[TheJaredWilcurt]

Description of the problem

In the documentation for Skinned Meshes it references "Imaginary functions" which aren't defined anywhere. So copying/pasting the code doesn't work.

• http://threejs.org/docs/api/objects/SkinnedMesh.html

Can we have the documentation updated so that calculateSkinIndex and calculateSkinWeight are defined or if they come from a plugin have that mentioned and maybe have a script tag referencing it or something.

I'd just like for this documentation to work out of the box so I can plug in the example into my code and have that basic thing work so I can build off of it.

[makc]

This very file comes with an example in it, which has imaginary functions implemented:

[TheJaredWilcurt]

If that's the functional version, why would you obfuscate it with undefined variables? That's just bad documentation. I don't go to the docs to solve a puzzle, I go because I don't know how to make something work. The purpose of documentation should be to explain something as simply and clearly as possible.

[makc]

Ah, so you are learn-by-copy-paste type ) The way I see it, you tried to leap over some steps and failed, next time just go one step at the time. When you step away from "hello world" examples, there will always be blanks that you will need to fill in and, until you learn how to do that (the step you skipped), copying code samples off the web will not help.

[makc]

P S

why would you obfuscate it with undefined variables?

Just to be clear, I am just a user like yourself, I did not write those docs

[TheJaredWilcurt]

Then why would you come here to promote poor documentation?

Me: The code example given doesn't work and should be corrected.
Random person on the internet: No, I think the problem is you.

[makc]

First thing that random person said was

This very file comes with an example in it, which has imaginary functions implemented

but you chose to ignore that, no wonder you are ignoring seond thing the random person said, too.

[makc]

And, btw,

I don't go to the docs to solve a puzzle

That's exactly what we do. We have a puzzle to solve and we come to the docs looking for clues. Not for solution - that part is the actual job we ourselves do.

[TheJaredWilcurt]

...wow

---

Edit: As apparently my comment was too easy to misunderstand, my astonishment was at the fact that someone could actually believe that you should intentionally write documentation like a puzzle. This was before I realized everything makc says is trolling, as nothing he says bears relevance to improving the documentation and in point of fact all of his comments and troll PR are for the purpose of making the documentation less functional and more confusing.

[makc]

...yeah

[carstenschwede]

@TheJaredWilcurt
I think the documentation should give you a general idea on how to use the stuff. I would not expect the documentation to include full-fledged examples - this is what the examples are for.

In this case the docs suggest that you need to calculate the indices and the weights yourself. It does not make sense to provide these since they are specific to your skeleton and model.

I get it that one can confuse syntax-highlighted code in the docs for a working example but I really think that this is the best way: Have a (probably not working) code snippet in the docs to illustrate usage and additional (working) examples embedded or linked to.

[TheJaredWilcurt]

How exactly would a functional version of the code, not illustrate usage?

I think the thing you are looking for... is comments. You comment the line above the functional code in the sample to state "This part will need to be changed depending your skeleton and model".

[makc]

Ok @TheJaredWilcurt I made PR for your suggestion )

[carstenschwede]

@TheJaredWilcurt

You comment the line above the functional code in the sample to state "This part will need to be changed depending your skeleton and model".

A) "This part will need to be changed depending on [...]" applies to most code samples in the docs. This is why they are code samples.

B) The doc currently read as

    // Imaginary functions to calculate the indices and weights
    var skinIndex = calculateSkinIndex( geometry.vertices, i );
    var skinWeight = calculateSkinWeight( geometry.vertices, i );

Are you confused about the term "imaginary" in this context or did you expect an explanation on how to implement the calculateSkinIndex and calculateSkinWeight functions?

[TheJaredWilcurt]

@makc I will now disregard any further comments from you as it is clear from your PR and other posts that you are a troll, as I refuse to believe anyone could post something so stupid without it being on purpose. Please cease from polluting this issue and derailing it from the purpose.

To help anyone who may have been confused by makc:

1. Have sample code that is identical to the functional example.
2. Do not display non-functioning psuedo code that benefits no one but the author.
3. If there are parts of the sample code that are only applicable to a certain scenario, note them with a comment.

---

@carstenschwede

My expectation is that whatever those functions do, they are shown and defined, or if they come from a plugin/other library that it is explained. The use of "imaginary functions" helps no one. You're purposefully removing parts of the code for no reason. The statement "just open the example in a new window and view its source" completely defeats the purpose of having the code sample on the page.

[carstenschwede]

@TheJaredWilcurt
Please see the documentation and the corresponding example to understand what skinIndices and skinWeights are about.

    // Imaginary functions to calculate the indices and weights
    var skinIndex = calculateSkinIndex( geometry.vertices, i );
    var skinWeight = calculateSkinWeight( geometry.vertices, i );

The values depend on how you want to associate vertices of your model with your skeleton. The implementation shown in the example only makes sense in the context of the example (for that specific model and bone structure) - you can't just copy/paste it for other geometries.

Adding all the lines of code that would be needed to turn a code sample within the docs into a working example would

• make the usage pattern harder to decipher (which parts do I really need?)
• make the docs harder to read
• create an overhead to keep actual examples in sync with doc.

Just like you said

The purpose of documentation should be to explain something as simply and clearly as possible.

I for one don't want to read through 20 additional lines of code, which are only needed to make the sample "copy/pastable" but are distracting from the core usage pattern. If I am looking for working code - I'll go to the examples folder.

[titansoftime]

How amazingly out of date the documentation is (especially the Animation system) is unbelievable. Defending it's current state sounds lazy. It needs a lot of work.

Makc, your comments make three.js look like a joke that no one takes seriously. Disappointing to see. Someone came here for help due to poor documentation and you went out of your way to not only make posts but an actual PR to insult them. Not very professional at all...

I too would like to see the documentation updated (the Animation docs are 5 versions behind).

[makc]

@titansoftime oh no, it was not hard to do that PR at all, maybe 1 or 2 minutes top (even though web editor failed, and I had to re-do it in locally). rest assured I would never go out of my way.

[mrdoob]

Even if @makc may be a bit too strong worded sometimes, he has been the one that solved this issue. So kudos to him! Also, thanks for pointing out this issue @TheJaredWilcurt.

[TheJaredWilcurt]

@mrdoob That wasn't a fix, he did that to intentionally be an ass. This is not resolved in the least. Merging in his joke commit is actually worse than doing nothing at all. Did you even read this thread?

His "solution" was meant to be wrong for the purpose of trolling. Stop feeding the trolls.

[mrdoob]

@TheJaredWilcurt

Did you even read this thread?

I did not read the thread in detail. Sorry.

What solution are you proposing?

[makc]

Assuming I am trolling @TheJaredWilcurt indeed, he never stopped to think why would I choose to troll him and help others on the same day, for example, in #8967.

Regardless, I do not think anyone can help him here.

[TheJaredWilcurt]

@mrdoob

1. Have sample code that is identical to the functional example.
2. Do not display non-functioning psuedo code.
3. If there are parts of the sample code that are only applicable to a certain scenario, note them with a comment.

This is basic stuff. There are a dozens libraries out there that do the same thing as jQuery. The reason it took off instead of the others was because the documentation was easy to use. They show the code, then show that exact same code in action. No confusion, no obfuscation. The obfuscation comes at the top explaining the basic principals, which you never have to read because the sample and example code at the bottom are simple enough to understand without the explanation at the top. Some things are little more complex, but at the end of the day, being able to take functional code and play around with it works in more scenarios than it doesn't. And the times it doesn't are where you need to read the explanation.

Creating your own version of jQuery is far easier than a library that handles 3D in the browser. You don't need to have great documentation to be the go-to library for 3D. But that doesn't mean you should use that as an excuse to have hard to use or outdated documentation.

There isn't a programmer in existence that hasn't copy/pasted code into their project to see if it works. That's why every time you google something the top result is stack overflow, and not a blog post explaining concepts for you to learn and manually implement (unless you're building a framework/library instead of using one).

Redoing all of the documentation to be easier to use and up to date would be awesome and according to @titansoftime it could use the attention. But that's not what I'm asking. I'm asking you to fix just this one page, so it meets those 3 steps I started off with.

[mrdoob]

I see I see. So your suggestion is that we should try harder...

I appreciate the criticism. I hope some day we'll meet your expectations.

[makc]

not to derail the thread (again) but this part

There isn't a programmer in existence that hasn't copy/pasted code into their project to see if it works. That's why every time you google something the top result is stack overflow, and not a blog post explaining concepts for you to learn and manually implement

is a spot-on. people hate to program (or, generally, to solve problems) and do it only if it's absolutely necessary. the one who creates the means for average Joe to program without actually programming will be next billionaire. and I do not mean this but some kind of tool that completely removes any need to know how the apis, technologies and languages. something like chat bot that would gradually build the code by asking you questions maybe. one day...

[TheJaredWilcurt]

@mrdoob

That would be great, but what I'm specifically asking is, can you, on this one page, clean up the sample code so that it is functional and uses no "imaginary functions".

[mrdoob]

Sure thing! I'll put that on my list of things to do.

[TheJaredWilcurt]

@mrdoob Thanks! 😄