-
-
Notifications
You must be signed in to change notification settings - Fork 4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Outdated links & example code in documentation #5207
Comments
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. |
Thanks for that - helpful. Based on this, I'm going to do:
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. |
Description:
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:
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.
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?
There's also a Glitch link here - again, probably worth keeping if we can, once we have updated working code.
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
References to A-Frame Physics System here - easy to fix so I rolled these into the branch referenced above.
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)
Outdated references to WebVR: move to WebXR.
Outdated references to Newsletter & Blog. Remove?
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:
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
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:
I think I'd be inclined to go for 4, but very happy to take whatever approach is your preference.
The text was updated successfully, but these errors were encountered: