Obviously these are just some examples to show how what types of questions could be included. There is much to be said about caveats, privacy, actionable feedback, and UX. This is just to start a discussion
First, let me state clearly that I do appreciate the effort and your committment to improve the doc (with I suppose the goal of reaching more users and overall increase user experience. In many cases, I would have supported this sort of communication operation but here, I don’t feel like it’s really needed and at least not at this time (of course, my opinion only).
From what I know, the documentation (and overall the support to learning/engaging with BJS, including with this forum) is already high. That doesn’t mean it cannot be improved and certainly doesn’t mean that this pillar of BJS success should not be sustained (quite the contrary). But then, we all know that maintaining the doc is work and committment. The doc have been revamped with v5 and are still not yet entirely through with this new build (there are still a number of issues with missing links, a search that could certainly be improved and also a number of issues from simply accumulating PGs without any distinction from what is ‘a simple trial (and fail)’ and what has been used as a ‘distributable’).
In short, I think the team and a number of the super users from the community already know what can be further improved in the doc. And the forum is also a place where new users regularly post their comments and first impression about the doc and the step-in with BJS.
If anything at this moment, rather than a survey, I would consider making it an ‘event’ (such as the current ‘bugs tracking’ event). Call on the community during a 2-months period to contribute to enhancing the doc (preferably with an incentive).
Of course, my opinion only and then again, I do like your desire and effort to make things better on the side of learning and communication.
I love your passion for the docs and LOVE the idea of getting community input on how they can be improved!
From broken links, to missing articles, we GREATLY value feedback from the community on how we can make them better!
I appreciate that you recognize that documentation is a subjective concept. It’s not something everyone understands so I appreciate that you recognize that your perspective is one of many. I’m sure @JohnK will greatly appreciate your approach to this.
I’m all for a survey or event, or other means to get community input on the docs.
Is that something you’d be interesting in organizing or driving for us?
Also adding @PatrickRyan to this thread for visibility.
I’ll only offer 1 small warning which is about high level organizational structure and the pitfalls of chasing too many voices on that subject. We all have many different learning styles…how we learn shapes our perspective of how we think the docs should be laid out. Over the past 3 years @JohnK and I have worked very closely together to listen carefully to community feedback and have done large sweeping restructuring of the docs twice. While I’m NEVER going to be resistant to improving the docs, I do think that we’ve landed on a really nice sweet spot for how the overall docs are organized.
Predominantly, (though not exclusively) we’ve found that there are 2 types of desired learning paths for people. 1 is to learn about the engine itself, learning the features, the API, how to use Babylon.js. The 2nd path is people who just want to get right into integrating Babylon into a web project. There is absolutely overlap in these two approaches, but there is also a different primary goal for each.
Anyways…I’ll stop rambling. I LOVE your passion about making our docs better and would LOVE to see you lead some further discussion about it. As a person who’s been behind the scenes of the last 2 massive restructurings, I’d just offer some kind wisdom that it’s a LOT of work, and that what we have now is definitely a sweet spot for many folks. Not to say we’re opposed to every changing the overall structure, just a word of wisdom that it’s a HUGE undertaking.
Hi, just let me address the most important points (as far as I understand them):
I’m not talking about making arbitrary changes, especially to the structure. That’s why I’d love to get some actual data, i.e., user feedback. Without this, everyone’s just guessing (which isn’t ideal)
My problem isn’t a lack of ideas, or even execution, but one of prioritization (given X time, what to do?)
Forum posts can indeed be used to generate more data points, whether manually or “automatically”. That’s why I mentioned sentiment analysis, it could be another avenue to pursue IFF that is desired
I think the “multiple learning styles” thing might actually be wrong, or at least that’s how I understand the research I’ve seen (bearing in mind that I’m not an expert). A mix of different methods may be better?
What you may be referring to is that users have their own goals, which may or may not be covered by one specific type of documentation. That’s why I usually advocate for a clear separation (example)
When it comes to potential improvements… my usual line of thinking goes like this:
I see something that I feel could be improved (excluding trivial stuff like typos or phrasing)
But why should it be improved and is what I have in mind really “better”? → Who knows?
At that point, you can either just make the change and roll back later if needed, or do nothing
In my own projects (and even at work) I’ve frequently just experimented, but that’s not appropriate here
Ergo, some amount of feedback (and be it just from the BJS team) is required to evaluate new ideas
But since I have a virtually infinite number of ideas, this wouldn’t be practical without “pre-filtering” or focusing (e.g. via user feedback, or even just priorities given by the BJS team - assuming they indeed have, as mawa says, a good overview of what needs improving and where the problem areas lie)
The result is that I just don’t do anything because I don’t want to add to the support burden for the team, or actively make the documentation worse for the users. But generally speaking, I’m always happy to lend my assistance and expertise. However, I’m not an expert in survey design or data analysis, so whatever I would be able to come up with to gather user feedback must be taken with a grain of salt (I can ask around first)
Just to be clear, I am not saying you did a bad job or that the docs haven’t improved over time (at all)!
