Why is there such a lack of documentation?

  • #1, by TurbineSaturday, 03. January 2015, 11:51 10 years ago
    Hi developers
    Please take the following as constructive criticism.
    As a new user I've been playing with your product for a few weeks but am frustrated by the lack of documentation. PLEASE provide some comprehensive documentation for your product! At the moment all I can find is a community wiki that while it's a good start (kudos to the community member(s) who have written it!) isn't comprehensive and only covers things at a high level. The other few tutorials/videos etc that I can find are all out of date and only cover some basics - there's a gap between the basics of your product and realising its potential that isn't intuitive. Nowhere can I find official documentation for the product, and as a result I have to scour the forums to find answers to some very basic questions that I would expect to be covered in the user guide. It's a seriously frustrating issue!!!

    I know you have to play with products for a while to get the hang of them and learn how to use them, and documentation can't cover absolutely everything, but if I'm going to spend my hard earned money on a product I expect to see documentation covering the vast majority of what it can do. Without it the lead time to learning a new product is substantially increased unnecessarily.

    Based on what the product can do I was expecting to purchase it - but my frustration with the lack of documentation and the resulting time its taking me to learn Visionaire means I will not be buying it at this time.

    If there is official comprehensive documentation available, can you please tell me where to find it. If it's in progress, can you please let me know when it's likely to be released. If there isn't any, then for the sake of your community, and potential future customers, can you please provide some ASAP?



    8 Posts

  • #2, by AkcayKaraazmakSaturday, 03. January 2015, 11:57 10 years ago
    Check this tutorial page mate; http://www2.visionaire2d.net/glenfx

    Great Poster

    440 Posts

  • #3, by marvelSaturday, 03. January 2015, 12:08 10 years ago
    Maybe I have an idea. What if each Power User would provide a single chapter documentation and we'd combine it to a WHOLE documentation at the end.

    I would participate on this... and I'm sure that we, the Visionaire Devs, would also invest some money for motivation. smile What do you think about it? Who is willing to join this community project?

    Key Killer

    598 Posts

  • #4, by TurbineSaturday, 03. January 2015, 12:49 10 years ago
    Thanks AkcayKaraazmak. I've been through all of those. Firstly they're not official documentation on the product - they're a good tutorial, but it's not the same as documentation. There's a lot of things in Visionaire that they don't cover - at the very least I'd expect a description of each pulldown/textbox in each menu to know what they do and how to use them.

    Next, they're a major release out of date, so when I followed them and had to do things differently and things didn't work, I wasn't sure why - and I've got nowhere to look to try and find out.

    If you can do things multiple ways, the tutorial doesn't tell you the pros and cons of each method, only a single way to do that step of the tutorial.

    And once you've completed those tutorials, what's the next step? I'm reasonably proficient in Lua, and though I can find example bits of Lua code on the forums, I haven't seen examples of how to link the Lua to the editor to make things work. I don't want to spend hours trolling the forums to figure out how to implement Lua code - if I could see several examples I'd be able to work it out from there, but all of this is unnecessary lead time to learn the product. There should be documentation to jump-start my learning process and make me proficient in a short timeframe, instead I have to figure out everything for myself (which as a result is a slow process) and waste unnecessary time when I want to be making games.

    Lastly, if I'm going to pay for a product, I expect to get documentation with it. Even a lamp you buy from the shop has documentation telling you how to use it - this product is substantially more complex than a lamp but there's no documentation at all with it.

    I know documentation time takes away from development time, but I think the lack of documentation would (a) be costing them sales, (b) be adding a lot of unnecessary support effort that could be done away with if the documentation was there to tell users how to use the product.

    Marvel : Just some feedback on this idea. From other products I've used in the past, documentation from multiple sources can be just as frustrating as no documentation. Everyone has different writing styles - documentation should be consistent in things like language, tense, diagram use, amount of detail about a topic etc - it's hard to get this consistency if the documentation doesn't come from a single source. But even if it didn't end up consistent, any documentation is better than none!!!


    8 Posts

  • #5, by afrlmeSaturday, 03. January 2015, 14:55 10 years ago
    Constructive criticism or not, doesn't bother me. Ok so to answer some of your questions/points...

    1. The official documentation is & will be on the wiki. (link is on the menu above).
    2. The old 2d wiki is more complete but is very out of date.
    3. VS has changed a lot since 3.7.1 to 4.0.
    4. Since 4.0 (or rather since Simon joined the dev team) VS has been getting overhauled, along with new features & improvements at a much faster rate which means the vs editor/engine is constantly changing.
    5. Visionaire Studio is not a full time business/commercial product/project. Most of the people working on it are doing so as an hobby in their free time & don't get paid.
    6. I am not a dev, I just provide support & documentation in my spare time. I also don't get paid, so there's nothing to warrant me sitting & working on finishing the documentation every day. I am also the only native English speaker on the team, although Alex & Simon's grasp of the English language is excellent

    One of the forum members (redspark) is currently working on a video tutorial series of how to get started in making your first game with Visionaire Studio. He's already uploaded 3 videos for it, with more to come. They are in English too.

    I would also like to point out that Simon is currently working on creating a new custom GUI for the Visionaire Studio IDE which means that most of the documentation will no longer be valid once that comes out & will probably have to be rewritten again from scratch. Having said that, I have no idea when that will be ready for release.

    I'm not sure why you think there is no documentation in regards to Lua script. It is probably the most heavily documented area of the wiki because it's mostly what I tend to focus on.

    http://wiki.visionaire-tracker.net -- new wiki
    http://wiki.visionaire-tracker.net/wiki/Manual -- manual (incomplete but mostly written by me)
    http://wiki.visionaire-tracker.net/wiki/Tutorials -- tutorials (video/text-image based by myself & other members)

    Lua documentation

    http://wiki.visionaire-tracker.net/wiki/Scripting -- introduction to lua scripting in VS with examples.
    http://wiki.visionaire-tracker.net/wiki/Data_Structure -- list of vs data tables/fields that can be accessed with lua
    http://wiki.visionaire-tracker.net/wiki/Player_Commands -- list of exclusive vs lua functions with examples
    http://wiki.visionaire-tracker.net/wiki/Common_Commands -- same as above but editor related
    http://wiki.visionaire-tracker.net/wiki/Remote_Debugging -- not sure about this (David wrote/created it)
    http://wiki.visionaire-tracker.net/wiki/Basic_lua:_Index -- a beginners guide to lua that I have been working on
    http://wiki.visionaire-tracker.net/wiki/Compiled_Index_of_Lu... -- a massive script index list full of scripts & examples written by myself, other team members & the vs community


    7283 Posts

  • #6, by patolandSaturday, 03. January 2015, 15:30 10 years ago
    Hi, I agree with Turbine, i can perfectly understand that Visionaire could be not a bussines enterprise but the price of the licenses truly are. I was going to purchase the full license for the mobile distribution and at the very last moment i opted for the 49 version to test, even aware of the lack of documentation...only to get frustrated by the imposibility to port my test game into any of my ios devices. The port does not work in my iphone 5, 6+ or ipad mini and i don't have a clue about why (there's no way to know if i did something wrong or not). I asked for help here and by mail and after more than 80 views i had not even an answer from the developers...You don't even mention is there's some kind of limitations to port games to ios in the main page and the tutorials for the ios porting are missing or incomplete.
    So with a really expensive license basis (490 for each game in mobile, c'mon guys!) and the poor or inexistant documentation i guess that the 4.1 is a powerful engine but it's not ready to be licensed. No offense here, just the facts. I'm very dissapointed.


    23 Posts

  • #7, by afrlmeSaturday, 03. January 2015, 16:11 10 years ago
    I can't provide answers for the technical side of the engine as I'm not qualified to do so. Things to do with export & platform support is up to the devs to handle/respond to.

    SimonS would be the best person to ask in regards to iOS & android exportation. I agree that the current mobile license is a little expensive as it's only valid for a single commercial game release only. The idea is that people should use the trial version or the indie licenses for the creation & testing of your games. There's no difference in exportation or features between the different license/versions of Visionaire Studio, other than what you are permitted to do, which is based on the current license you hold.

    Both the indie licenses allow you to create & export as many games/projects as you like. Although they have certain limitations in what you are allowed to do in comparison to the mobile & professional licenses.

    The mobile & professional licenses are just there for if/when you decide to release your game commercially to mobile platforms or as a physical product in retail stores. You don't have to purchase them until you need them.

    In regards to platform support & export guides, there are 2 pages on the wiki about that, which were mostly written by the devs. 1. is about the minimum & recommended system requirements for os & devices & the other is a guide on how to export/compile for each platform. The pages can be found here & here.

    I would like to point out one thing. I have no intention of creating step by step documentation for the editor itself. It will be a summary/overview of each section & what it does. I may provide the odd step by step guide to certain things but more likely than not, those bits will be provided by other members of the forum community or vs team.


    7283 Posts

  • #8, by SimonSSaturday, 03. January 2015, 16:53 10 years ago
    @patoland: Hi there, I'm sorry you didn't get an answer, problem is that the dev that handles apple stuff and their licensing isn't active at the time. Probably the certs have timed out, you could try jailbreaking (I never said that). Apple will continue its anti-dev campaign in the future (of course they say we have the best app store there is), now they are completely removing all options to make custom ipas, so we can't anymore provide you with client-side ipa-export once they do that (this year). So you would be forced to buy a licence from Apple or jailbreaking your device. Android will be still supported and I'm trying to help as many people as possible with that in my time. My support in the forum is taking a big amount of my time.

    The mobile licences are so priced, because (I said it often before) you are buying our support time, as we need to help you with everything considering Apple Store and Google Play Store, and that is not done in some hours believe me.

    As for documentation, it's not easy to create something like that without one willing to do a lot of work to keep the quality and always bettering it. I for my part am doing what I'm best at, pushing the development of the engine, I can't afford much time for the docs without reducing the amount I program. Simple as that. As everyone else here is employed (I'm studying at the time), they also can't afford the time. So we rely on people writing something, recording videos.

    Thread Captain

    1582 Posts

  • #9, by afrlmeSaturday, 03. January 2015, 17:23 10 years ago
    Cheers for explaining that Simon. smile

    I did mean to mention that everyone on the team either have full time jobs elsewhere or are engaged with other things, like university in Simon's case, or the CMS/website company that Thomas (Marvel) runs, etc...

    I'm currently helping develop a game & I have stuff I have to do at home too, so my time is more focused on those things, instead of the engine documentation.

    Simon did make a good point about the writing of the documentation too... It is very time consuming, especially having to think how to phrase things in a way to make it easy enough for everyone to understand & then going over & over the content again to make sure grammar/spelling is correct & that it sounds ok. Also the diagrams & screenshots also take a little while to do; especially if they contain annotation over the top of them explaining various things. To create a screenshot I need to open the editor, print screen, open photoshop & then paste the image into photoshop, crop, edit & export, then upload which probably takes 5+ minutes per image.

    The most recent page I wrote which was one about recommended image formats for Visionaire Studio & along with a mini-guide to encoding/conversion/exporting your images to .webP format (with screenshots) took me over 20 minutes to write & that was only a small page.

    The few tutorials I have provided in the wiki, took me hours to create & write as I provided the .ved & resource files as well as a step by step tutorial for what I did.

    The few shader function examples that are currently on the wiki in the script index also have .ved & resource files that I created & provided as examples, all of which probably took me anything from 20 minutes to over an hour to create. There was actually more examples before but an error occurred a few months back & we lost quite a few of the wiki pages. The dev that handles the apple stuff (as Simon mentioned earlier) also helps me with wiki programming & has since added an automatic backup system to the server so we don't lose anything again. smile

    As I mentioned before: I mostly focus on the Lua side of the Visionaire Studio. I also recently spent a lot of spare time sorting out the new wiki themes. David changed us over from the basic theme to the bootstrap framework, which I then wrote the code for the theme changer & the style sheet code, which took me about a week or so.


    7283 Posts

  • #10, by patolandSaturday, 03. January 2015, 17:55 10 years ago
    Hey Guys, thank you for your answer! I understand that you're making a big effort, but having a great engine without a good documentation, is a little bit pointless, i hope to collaborate with some tuts if i go with your engine in the future. At this moment, i'm not sure as regarding the IOS exporting i still don't get it. I have an apple develop. account and i need a tool to make my ipas fron VE without jailbrake my devices. I also spent a lot of time trying to figure out what's not working. So, i just like to know if this feature is working or not?
    Thank you so much!


    23 Posts

  • #11, by TurbineSunday, 04. January 2015, 12:03 10 years ago
    Just to clarify my earlier comment about Lua - the problem is not the writing of the Lua code, it's how to integrate it into the editor. Yes there's demonstration code available, but the tutorials/wiki don't focus on how to integrate it into your game/the editor - just here's a sample of code that should do xyz, figure out how to make it work yourself. It's the examples that show you how to get things working from beginning to end which are lacking.

    AFRLme - for documentation purposes I find greenshot (http://getgreenshot.org/) saves me time as it does the screenshot and cropping in the one action, hopefully you'll find that helpful.

    Simon - I understand that this isn't a full time job for the developers, so documentation isn't high on the priority list. I'm just providing you feedback that as a customer if I pay money for a product I expect to have enough information given to me that I know how to use it. If that information isn't available I'm not likely to spend money buying it - hence why I haven't bought a license at this point. I hope you are not losing many sales to other potential customers who feel the same way. Maybe more documentation would bring you more customers and hence make you more money?


    8 Posts