search

aframevr / aframe

:a: Web framework for building virtual reality experiences.
https://aframe.io/
MIT License
16.69k stars 3.98k forks source link

Frustrating Broken Documentation #5154

Open everythingability opened 2 years ago

everythingability commented 2 years ago

Hi,

on the AFrame github home page there is a code sample (the that loads AFrame version https://aframe.io/releases/1.3.0/aframe.min.js but the Glitch link that demos this code sample loads AFrame version https://aframe.io/releases/0.5.0/aframe.min.js

The ocean component doesn't work with 1.3.0.

There are heaps of examples, really great examples, that don't work with 1.3.0 and are hosted on CodePen or wherever, but they're annoying as hell to come across because so many of the examples don't work with the current version of AFrame. And there are hundreds of examples out there in the wild on Glitch and elsewhere basically making 1.30 really hard to learn.

Whilst I appreciate that "things move on", can the official docs of AFrame do something to either flag that certain features/demos only work with previous versions, or even better, have a tidy up of the documentation, making sure that the linked samples and examples provided do work with the current version of AFrame.

Thanks

everythingability commented 2 years ago

Here's a good example within the docs (there are loads)

https://aframe.io/docs/1.3.0/components/cursor.html#states

The Visual Feedback section (although I'm looking at 1.3.0 docs) it links off to a CodePen example which doesn't work in 1.3.0

AND to make matters worse the docs have a "suggest an edit on Github" link (where I would have made this complaint) but I'm lead to a page that asks me to fork the documentation and put the change in there (what?!) , rather than just report an outdated resource.

dmarcos commented 2 years ago

Sorry for the inconvenience. Docs are hosted on github so a pull requested is the most effective way to suggest and contribute changes that can be directly incorporated. A github issue is also fine. Notice this is community maintained.

What other outdated links besides https://aframe.io/docs/1.3.0/components/cursor.html#states have you found?

There are heaps of examples, really great examples, that don't work with 1.3.0 and are hosted on CodePen or wherever, but they're annoying as hell to come across because so many of the examples don't work with the current version of AFrame. And there are hundreds of examples out there in the wild on Glitch and elsewhere basically making 1.30 really hard to learn.

In the docs or third parties? We can improve the docs but unfortunately we cannot track and update every single example out there.