Outdated links & example code in documentation

[diarmidmackenzie]

Description:

• A-Frame Version: 1.4.0
• Platform / Device: all
• Reproducible Code Snippet or URL: See below.

There are a range of very out-of-date links in the documentation, especially the getting started guide, that it would be great to fix.

Since upgrading to 1.4.0, aframe-teleport-controls has been broken. I was concerned about this as I knew it was referenced from the docs. Discussing with @vincentfretin we agreed that it would be a good idea to change the docs to refer to blink-controls, which is an actively maintained teleport component.

I started working on this here, but in the process of updating the docs, realized that there are a heap of similar issues that have stacked up.

Just considering the pages I've been editing, and a little bit of additional digging, the other issues are:

1. Various outdated references to the A-Frame Registry. Easy to fix these to refer to the new Component Directory on the wiki, so I did that on the branch above.

2. aincraft source code built in the example is also referred to as being in GitHub here in CodePen here, and in Glitch [here]( - all substantially out of date. Suggest we update the GitHub version to match the code in the tutorial, and retire the CodePen version.

Not sure about the Glitch version - I think it does add value over & above GitHub + GH Pages due to the remix option, so probably worth keeping. I assume there is already a set of Glitch demos that do get updated on a per-release basis, so shouldn't be too much overhead to add this to that list? (once we have an up-to-date working version on GitHub). I'm guessing only @dmarcos has access to the A-Frame Glitch account?

3. The ECS tutorial page makes extensive use of the aframe-particle-system component, which has had a string of recent compatibility issues... @vincentfretin and I recently discussed bringing this into c-frame and under better maintenance. If we do that, we could update this page to refer to that version.

There's also a Glitch link here - again, probably worth keeping if we can, once we have updated working code.

4. The Building a 360 image gallery probably needs a bunch of updates similar to the Minecraft Demo, needs Glitch updated etc.
   https://aframe.io/docs/master/guides/building-a-360-image-gallery.html
   Currently it runs at 1.0.4

5. References to A-Frame Physics System here - easy to fix so I rolled these into the branch referenced above.

6. Lots of references to A-Frame Extras. These should also refer to c-frame now (non-c-frame 6.1.1 is broken as of 1.4.1). I'll fix these up in the same way once we have a 6.2.0 release that is compatible with A-Frame 1.4.1.

Other things I spotted that could do with fixing up (and I'm sure there's more, I didn't do a comprehensive review of the docs)

7. Outdated references to WebVR: move to WebXR.

8. Outdated references to Newsletter & Blog. Remove?

9. Outdated reference to supermedium browser. Remove?

Netting this down, there's a lot here altogether.... I probably didn't spot everything, but I think the scope above is feasible for me to take on fixing in fairly short order.

Proposed scope:

• All links to recently adopted c-frame components updated.
• The following demos working with 1.4.1 + compatible components, documented + working versions on GitHUb + Glitch:

1. aincraft
2. 360 gallery
3. ECS example (aframe-registry example on Glitch)

• Get aframe-particle-system adopted by C-Frame, and that version referenced by docs.
• Other minor items mentioned above
• Remove links to outdated code on codepen - glitch links are sufficient.

There's obviously a ton of other examples that are out of date, and there's another task to try to fix those up, but I think making it a priority to fix the examples explicitly used within the docs makes sense...

My dependencies on @dmarcos and @vincentfretin

• Initial review of the above & buy-in to me making these changes. Are you happy with this all in one PR, or do you prefer to break it down?
• Final review of updated docs/code
• Once example code updated on GitHub, push updates to A-Frame glitch account.

One specific question where I'd appreciate input from @dmarcos: in several places the current docs explicitly name-checks certain community contributors, e.g. Don McCurdy for aframe-physics-system, aframe-extras, Fernando Serrano for aframe-teleport controls, IdeaSpace for aframe-particle-system.

Would you prefer to:

1. continue to name-check the original contributors, even if they are no longer the maintainer
2. name-check both original author & current maintainer
3. just name-check the current maintainer
4. or not include any names at all, and rely on GitHub repos to give credit where it's due?

I think I'd be inclined to go for 4, but very happy to take whatever approach is your preference.

[dmarcos]

Thanks! In general I lean towards removing 3rd party links from the docs and make it as self-contained as possible. As you see maintainers come and go, stuff gets out of date, hard keep track of and maintain.

I would remove any references to 3rd party components, codepens and glitches in the docs. Can have a wiki or a dedicated section in the docs with perhaps recommendations but not sure yet. References in the same place are easier to verify and QA before a release.

For some of the examples / sample code in the docs replacing external links with an example (https://aframe.io/aframe/examples/) might be the best. I use the examples to QA releases and tend to reveal many outstanding issues. We can give attribution to example author / maintainers. We have a system in place: info button https://aframe.io/aframe/examples/showcase/model-viewer/

Can indeed remove links to discontinued products / apps.

If above sounds reasonable feel free to open a PR and can discuss case by case there.

[diarmidmackenzie]

Thanks for that - helpful. Based on this, I'm going to do:

• 3 PRs to move each of the examples referenced above into this repo's examples: (https://aframe.io/aframe/examples/)
• Another general clean-up PR to tidy up other bits of the docs along the lines you suggest.

I'm happy with the steer to minimize references to 3rd party stuff. My inclination is probably not to eliminate in all cases, as I think a small number of direct links will help readability / docs quality - but we can discuss details in the context of PRs.