Three.js: Update Github Wiki or move it to Docs?

[DefinitelyMaybe]

Hey all,

So I believe the github wiki is the first main source of info for new developers to the repo. As far as I'm aware, only collaborators can update it. It may be an idea to create a new section in the docs instead of using the github wiki. Perhaps putting contributors under the Code section of the main page.

As well as migrating the github wiki, I can think of an addition that might make various peoples lives easier, a "common issues" page (think issue posted, instant close, link to part of common issues). There are also some random pages which could be removed i.e. API reference. Those are two bits and pieces that come to mind but I'm sure others have more ideas.

It may help sort out miss-communication, speed up reviews and/or ease the barrier to entry.

I'd be happy to flesh out a first draft but I ain't starting that until I've got the proper feedback.

[mrdoob]

Moving the wiki to docs would mean that we'll have to translate to other languages too...

I agree that we could improve the Wiki to be a better starting guide for contributors though!

There are also some random pages which could be removed i.e. API reference.

Deleted it. Thanks!

[DefinitelyMaybe]

Moving the wiki to docs would mean that we'll have to translate to other languages too...

noted. not the worst thing ever but would be more work.

I agree that we could improve the Wiki to be a better starting guide for contributors though!

right. stick with the wiki. I shall draft up all the different amendments I'd like to make.

[looeee]

Maybe we could link to the wiki from the docs?

For example, we could add a "how to contribute to three.js" manual page that tells people to check out the wiki for more info.

[Lecrapouille]

So I believe the GitHub wiki is the first main source of info for new developers to the repo.

Hello to everybody! In my opinion, in 99% of projects, the software architecture document is never given (GitHub projects as well as professional projects) ! You know this precious document with UML diagrams, sequence diagrams or state machine diagrams, explaining how classes are linked/interact together and giving a global overview on how the software is working (algorithms). This is sad because as @DefinitelyMaybe said wiki is the first main source of info for new developers but I would also say is: whatever doc or wiki are offered, they shall offer a nice paper describing algorithms, how the code is implemented, what each file/folder is offering (ie. add a README.md in each folder) and this is the first thing I'm looking for when discovering a new project.

I always ok to offer my contributions to other projects but when no architecture pages are given or no enough comments inside the source allowing an easier understanding this makes people less open to contribute to the project (or contribute to an equivalent project) because we pass more time to understand details (which is language-specific) than global ideas behind algorithms. Still in my opinion, once you understand algorithms implementation is less a problem.

[DefinitelyMaybe]

@Lecrapouille thank you, though I wouldn't go as far as UML diagrams and I'd probably stop at a board strokes explanation of the overall architecture. Things change.

This is sad because as @DefinitelyMaybe said wiki is the first main source of info for new developers

I am not the source of truth on this matter. I may have missed some other document somewhere.

[Lecrapouille]

@DefinitelyMaybe I know! My comment was just a general-purpose: an ideal way to do! A unique, simple and small PDF well wrote made in LaTeX is more preferable to a lot of unfinished wiki pages.

I stop my trolling I'll not disturb anymore this ticket :)

[DefinitelyMaybe]

I've completed a first draft of what could be the new wiki page.

It's available via this link as part of a shared google folder.

Everything within the link is editable.

Comment as you wish, I will check back on it later but will also close down the link as soon as this issue is resolved.

[looeee]

This looks like a nice simplification of the wiki.

I'll put my comments here rather than the doc.

Purpose of the Wiki
Quickstart
The npm Scripts
Contributing

These sections should just go on the main page instead of the table of contents. There's only a few hundred words total, and in any case, the TOC is duplicated to the right-hand side.

If you add a new feature it's good to also add an example and screenshot for it, for showing how it's used and for end-to-end testing.

I think that not all new features will need a new example. For simpler features, it's often better to incorporate into an existing example to prevent the list of examples from growing ever longer.

To prevent people wasting effort before it's clear that an example will be required, maybe better to phrase this as "you may be asked to add an example demonstrating the feature".

Also, we should ask people to update the docs whenever they make a change, and perhaps note how that works with the Chinese docs (I think we just copy the English to begin with).

If you add some assets for the examples (models, textures, sounds, etc), make sure they have a proper license allowing for their use here, less restrictive the better.

Also ask people to reuse existing assets if possible, and note that large assets are unlikely to be accepted.

This project is currently contributed to mostly via everyone's spare time. Please keep that in mind as it may take some time for the appropriate feedback to get to you. Sometimes it’s easier to ask first about doing x, y, z than to make a PR with x, y, z and be told no (or even no to y and z but x is cool).

This could be simpler. Maybe just "If you are unsure about adding a new feature, it's best to ask first to see whether other people think it's a good idea."

Common Issues

I don't think this section is needed.

npm run dev

Nit: I've always had the impression that "npm run start" is pretty close to the "standard" name for this task. Maybe we should suggest that instead of dev?

Using SketchUp Models

I'm not sure why this page is in the wiki. Maybe we should remove it?

[mrdoob]

Looking good to me!

[DefinitelyMaybe]

@looeee take another look when your ready. I've incorporated your suggestions.

[looeee]

Looks great 👍

[DefinitelyMaybe]

cool. shall we wait for other input?

[mrdoob]

@Mugen87 @WestLangley what do you guys think?

[Mugen87]

I've always had the impression that "npm run start" is pretty close to the "standard" name for this task. Maybe we should suggest that instead of dev?

You can actually use just npm start which I would prefer instead of npm run dev. Besides,npm run test should be npm test.

[looeee]

You can actually use just npm start

Oops, yes that's what I meant.

[DefinitelyMaybe]

sorted. using npm start and npm test. Think we're ready to go.

So ah, I don't have permission to edit the wiki. I'll leave the doc files here for whomever has time next . I'm closing down my links.
Landing Page.txt
Landing Page.pdf

Whomever does the editing can close this issue, or I'll do so once I notice the changes.

[mrdoob]

@looeee would you like to take care of this?

[looeee]

Sure, I'll find some time this week to do it.

EDIT: actually, I won't have time for the next while. If someone else wants to do it in the meantime, go ahead 👍

[DefinitelyMaybe]

thanks guys. I do hope this helps future devs

[munsocket]

@DefinitelyMaybe continuing talk in #19395. I can't be responsible for this because I am not a native speaker and can't check your contributions properly. You probably see how bad I am in this.

[DefinitelyMaybe]

I think you'd do just fine. looee's already been over the doc (linked above) so its pretty much just a copy and paste. More than happy to work through anything else that pops up :)

[munsocket]

@DefinitelyMaybe ha-ha thanks, but I am not a collaborator now :) I just can check the gist.

[DefinitelyMaybe]

hey @Mugen87, so #19520 was merged nicely and in that PR I said that it could be a good replacement for the wiki changes but.. as the wiki currently stands, it's still a lot of old information. I'm not sure this issue should be closed yet.

• should one link to the other? or
• should the wiki be removed?

[looeee]

should the wiki be removed?

I vote to move any developer info from the wiki to docs/Developer Reference.

[Mugen87]

TBH, after removing the "How to contribute to three.js" wiki page I don't see a demand for action anymore. The remaining wiki entries seem okay to me.

[DefinitelyMaybe]

looks left, looks right .. right.