Documentation feedback wanted - What would you like to see improved?

We are looking to improve our documentation and really want to focus on areas that have affected our community the most. We would love to hear your feedback about using the documentation and tutorials so we can do our best to act on it! :slight_smile:

Topics include (but not limited to):

  • What are we missing that turned into hours long search on the forums?
  • What do you need that is not available yet?
  • How easy/hard is it to find the information that you need?
  • What are your common use cases for projects
  • What would be your ideal/dream documentation site/flow?
  • Are the tutorial samples enough?
  • How do you go about looking for information?

Looking forward to hearing your feedback :grimacing:!

2 Likes

Perhaps, I could share my experience with Playcanvas, even though I am still learning it.

The very first steps for me were to go through the User Manual and afer that checking all Tutorials. Most of the tutorials are just projects, demonstrating a feature of the engine. I didn’t go through the code, but simply looked what was possible with it. Later, when I started my first project and had a need to implement a feature, I was like “Oh, I think there was some example that showed something similar to it”. I would then go through the tutorials again and try to find it.

Probably the most informational and valuable from the learning perspective for me was the Keepy Up tutorial series. It introduced me with most of the important basic concepts of the engine and how to use them. After completing it, I was able to create my own game. I think it would be nice, if there would be more tutorials like that. The good thing about the series is that they not only show how to use a feature (like in most of the examples currently), but also can explain why it is used this way or another.

My dream documentation would be the one, which doesn’t require me to look anywhere else for the information. For example, at some point I was learning how to use Firebase and its services. When the time came to do the developement, I rarely googled the questions I had - all the info is easily available through their documention guides and videos.

Playcanvas has a forum with an amazing community to support most of the questions during the beginning of the learning path. I’ve learned a lot from asking here (still can’t think of a way to properly thank Leonidas for every bit of wisdom he shared). After learning something new, for example, batching or object pooling, that I am not familiar with, I would then google and try to read as much as I can about the topic. Then I returned here, read the guide to see how the engine does it and try to use in my own project.

The thing is though, I have read that guide about batching guide before. But since I had no previous experience in developing games (or 3d graphics in general), I had no notion of what it means and whether I really need it. So, when the time came, I didn’t even remember about it, until I was pointed to it. Probably, some tutorial series could be added where perfomance topics would be covered.

In the more recent times, I am fighting with the index and vertex buffers. Even though I am already familiar with the concept, e.g. what they are and why they are needed, I still don’t have a clear understanding on the graphics pipeline of the engine. For example, it is hard for me to take a standard WebGL code of drawing a primitive and map it to the engine calls that I am required to execute in order to do the same thing. There is a vertex buffer iterator, but do I actually need it to iterate through the buffer indexes, and what happens if I don’t lock the buffer before doing so, or why would I need to lock it in the first place. Similar questions to these are not really explained in the guides and most of the time I spend reading the engine source code.

2 Likes

I would like to share my experience with Playcanvas too.

I started learning Playcanvas approximately 3 years ago. When I opened the User Manual for the first time most of the stuff were making sense, given that I was coming from Unity and everything seemed quite familiar. But when the time for coding came and I opened the tutorials, I felt a bit overwhelmed by the fact that, most of the tutorials were just a Playcanvas project. Which was great in a sense that, I had the chance to study how someone would organize the hierarchy, the codebase etc. I have to say I wasn’t a JS expert at that time so I was struggling with that too, so walking through another’s person’s codebase was really really hard. And to be honest I just closed the page and left.

But, driven by the idea of developing games and 3D content on the web and share them very easily without having to install anything or compile any code, I came back pretty quickly.

Some things I would love to see in the documentation:

Some beginner level tutorials teaching Playcanva’s API and why not, some Javascript? That would attract people that they won’t have to know Javascript.

Some tutorials on 3D maths and the most common concepts in Game Development. (priceless!)

Some advance tutorials like shaders and GLSL or even performance optimization

I could propose ideas until tomorrow but my point is, that the goal of the Documentation could be to help people with no Game Development experience to easily getting started and feel welcoming in Playcanvas.

An example I can share is Godot’s Documentation: https://docs.godotengine.org/en/stable/

3 Likes

In general I find the documentation very neat.

Personally, I am not an intensive user of the documentation. Sometimes I use it when I receive a link from someone. When I go to the documentation to be able to give feedback I immediately notice that almost all my points of attention are about the terms used.

Is the documentation different from the user manual? Or is it the same thing? In that case I like to see a “Manual” button instead of a “Docs” button. When I click on the button I get on a page “PlayCanvas Developer Resources”. Is that the same as “Documentation”?

Personally really like the tuturials. I’m looking for the tutorial that matches and then I use it as an example for my own project. I would remove the extra “Editor” button to avoid confusion and duplicate tabs. I also would rename the “Tutorials” to “Examples”. Then you can create a separate section for actual tutorials to follow.

In addition to the tutorials, I regularly visit an API Reference. Here I really miss enough explanation and examples. Sometimes I just end up on a page with only title headings.

Furthermore, I would like to see a little more contrast between the different parts on a particular page. For example, give all examples in use an orange background tint.

2 Likes

Working with others people Unity scripts is about the same experience, granted there is much more of middleware/modules available in the asset store or what you can ‘creatively’ lift from others unity git repos; however your ability to interpret others code to do what you want is often more useful than the ability of taking someone else predigested code from some tutorial…

2 Likes

Thank you everyone for the feedback, it really means a lot to receive such detailed replies.

I will collate ideas going forward into a GitHub issue on the documentation site sometime this week for more detailed review and feedback.

This brings up a more general point that was commented on by @Thomas_Due_Nielsen in another thread about concepts that we use such as batching, variable scoping for callbacks, etc that we don’t really explain or point to other resources to learn more.

Definitely something we need to add.

We definitely need some way to split the two.

We are thinking about adding more thorough information and mini examples in the API docs. In some areas they are a bit thin.

That is too thin :sweat_smile: If you see them again, can you post a bug about them either on the forums or the GitHub page please? https://github.com/playcanvas/developer.playcanvas.com/issues

Shaders and GLSL will be given a little boost as we are working on a system to make making shaders a lot easier at the moment. Noted that we should extend our optimization section too.

5 Likes

Documentation is often not detailed enough (like raycastresult detail in raycastall).
Sometimes there is not enough link to github with a class (like rigidbody layers and trigger research).
Sometimes description wrapped by using others naming (like material vs standartmaterial - where description with difference?).
May be create special topic with docs edit request?
Code examples in docs are good and do not cause additional questions ))

1 Like

Thanks @KpoKec!

If it’s to do with the API, please post feedback on the engine repo as that’s generated by JS docs.

Tutorials and the user manual feedback would be in this repo https://github.com/playcanvas/developer.playcanvas.com/issues

Good point, we should really make that more clear which one should be used.

1 Like