First let me say, without intended butter-up or brown-nosing, that the three.js documentation is extremely easy to use, good-looking, and all-around slick. But that makes me wonder: How the heck is it created/maintained? I’ve written HTML docs before, and found the experience to be dreadful. But I also don’t see anything in the docs (heh) or examining the code or scripts that suggests it’s anything less than a manual effort. And if it is manual, what is being used to style the page and run the filtering? Was it all home-grown? If so, bravo, and can I somehow use/license the framework? 
1 Like
Yes 
. The documentation is not auto-generated from source code (JSDoc) but manually maintained. It does not use any external libs. All features are based on custom code.
Smart devs could argue that it’s unprofessional to maintain a documentation like that for such a large project. But it’s important to understand that there are historical reasons for the status quo. Changing it now would require a lot of time and effort, so it’s easier for us to stick to the current approach and focus on other topics.
If we could start from scratch, I would vote for using JSDoc and a (customized) documentation template. It’s easier to maintain and you can achieve a similar visual appearance.
2 Likes
I wouldn’t call it unprofessional, but there is a definite disservice being done by not having the docs be generated. I understand the historical implications (once you choose a paradigm it’s often easier to just maintain it than it is to change), and can definitely see where trying to muscle things like live demos into the JSDoc paradigm would be a lot of work. Just color me surprised.
Looks like the concept was brought up and didn’t really go anywhere due to lack of internalization and a distaste for in-code docs.
I think it would be possible to find a solution for the I18N topic. And I’m truly convinced that code and documentation belongs together. It’s a huge help when you read code and try to figure out what’s going on. Especially in a dynamically typed programming language.
Digressing a little, I definitely agree. Beyond basic inline understanding, there’s also a functional component. You can generate a TypeScript Definition file from documented code. Some editors even use documentation for their code-completion/-hinting implementations (VSCode for one). Just more fuel for the fire. 
2 Likes