Outdated links & example code in documentation
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 17.6k
- Forks
- 4.4k
- PR merge metrics
- No merged PRs in 30d
Description
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:
-
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?
- 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.
-
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:
- 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:
- aincraft
- 360 gallery
- 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:
- continue to name-check the original contributors, even if they are no longer the maintainer
- name-check both original author & current maintainer
- just name-check the current maintainer
- 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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the getting started guide and the linked teleport-controls-to-blink-controls branch, then inspect the named ECS tutorial, 360 image gallery, and HTML-and-primitives example. Check the current links and example versions before changing anything; done means the explicitly listed documentation links and demos point to maintained, working GitHub and Glitch versions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation, web-dev
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100