Biggest documentation WTF i have (not) seen



  • Check out this page. It's a homepage of a fancy, cool, and pretty extensive GUI library for XNA (windows/xbox game dev framework, for those who don't know). Thanks to its size and capabilities, its API isn't really intuitive to use, even if it once, on the beginning, maybe was.

    Now here's the challenge: find the documentation.

    ...how long did it take you to (fail and) give up?

    Challenge no. 2: google some tutorials.

    Again, how long did it take you to give up?

    Long story short, there is NO documentation, and NO tutorials, exept one which is just about absolute silly basics one could figure out by himself, and even THAT ONE is located in a wiki for completely unrelated project, and was written by someone who has nothing to do with NeoForce.

    To be absolutely clear, NO documentation. NOT EVEN methods/properties summaries (those short descriptions that show up in IntelliSense popups), nothing. Nada. Null. Zero.

    And for the WFT to be complete, then I find .chm file, in its installation directory, and open it, only to find out, that it contains just the library structure and listing of functions ("reference" without ANY information exept what you can already learn by browsing through api with the help of IntelliSense in Visual Studio).

    I mean, dammit, this is the moment I fully realized the truth of "Bad documentation is thousand times better than none".

    The final and last strike: this project seems to be up and running (and BEING USED, really, though I had trouble to believe it too), for AT LEAST A YEAR!!! I mean... have you EVER seen any technology/library/anything existing for such a time, that has NO TUTORIAL written, by ANYBODY, WHATSOEVER?

    (It may not look so bad when you're reading it, but believe me, if you'd be finding this out gradually, you'd be crying, shouting, screaming WHAT THE FUUUUUUUUUUUUUUUUUUUUUUUUUUUUUCK(?!?!) every five minutes, with every of this "(non)discoveries".

    I'd be utterly fascinated, if I could not feel the rage...

    (Oh, and don't even say a word about code samples, which cover, AT BEST, less than 1/4 of the library.)



  • Really, what are you expecting from Czechoslovakia?



  • @tster said:

    Really, what are you expecting from Czechoslovakia?
     

    thank you, but we're two separate countries* for about 21 years by now, and besides that, Tom Shane isn't really czech name. it's more likely that it is on .cz because it was cheaper than .com or the likes

     

    * czech republic , slovak republic (slovakia) , learn the difference already, you're programmers, you're supposed to be able to learn fast



  • Well, if it makes you feel any better, I write code everyday to an enormous API which has tons of documentation, but which is almost always wrong and misleading. 



  •  minor added could-be-called-classic wtf - confirmation mail from their forum registration contains username and password (which you set in the registration itself)



  • @tster said:

    enormous API which has tons of documentation, but which is almost always wrong and misleading. 
     

    "Dear Lord, please, give me at least documentation which is almost always wrong and misleading, and take my soul in exchange, if you want."

    (in that case, there would be tons of forums arguing about it, i suppose, so you could get it right... probably... after some (long) time... or at least you could have hope, that maybe, just maybe, the piece you need to use at the moment, is one of those few which are little more right than wrong. What would I give for the sheer hope...)



  • So do you have the source code to the library?  That's what saves me.  I always look at the source code to figure out that the behavior is.



  • @tster said:

    So do you have the source code to the library?
     

    it has a "Source" folder, but files in it, though similar in theme, seem to be either absolutely outdated, miserably incomplete (same as the example codes), or completely unrelated to the actual library. Also, something tells me, that learning to use this specific library from source code would take approximately the same amount of work and time, to write it from scratch, which kinda defeats the purpose of 3rd party libraries, doesn't it?

     (And yes, the basic package is free, and you can buy package with complete source, but, would you buy something as (un)documented as this?)



  • @SEMI-HYBRID code said:

    I mean, dammit, this is the moment I fully realized the truth of "Bad documentation is thousand times better than none".
     

    Agreed. If nothing else, when there's bad documentation, someone must have written it, and that person can (in theory, at least) be found and struck repeatedly with a cinder block. It's usually much easier to find and exact violence upon the person who wrote bad documentation than the person who should have written documentation when there isn't any.



  • @Someone You Know said:

    that person can (in theory, at least) be found and struck repeatedly with a cinder block. It's usually much easier to find and exact violence upon the person who wrote bad documentation than the person who should have written documentation
     

    I like your train of thought, there.



  • Are you paying to use that API? Because if it's free, well, you get what you paid for.

    Even if that'ws not the case, you should have taken the documentation void into account before choosing to go with the API.



  • [quote user="Renan "C#" Sousa"]Are you paying to use that API? Because if it's free, well, you get what you paid for.[/quote] 

    as i already wrote, it's got a free and paid version, the only difference being that with paid version you get the source too. i repeat: even the paid version doesn't have any documentation.

    [quote user="Renan "C#" Sousa"]you should have taken the documentation void into account before choosing to go with the API.[/quote]

    i chose it because it seems to be the only xna gui that's usable (in terms of performace and features). i assumed that since there's no docs on the page, there will be something in the download package. turns out, you really make an ass of yourself when you assume things :-). i'm currently waiting for some response on their forum. if it won't be of any use, i'll probably have to code the gui by myself (which i really wanted to avoid).

    btw, it turns out that whole xna gui libraries situation is quite WTFy - there's about 5 of them, two of which are utter piece of shit, one is incompatible with the current XNA version, another one is the Neoforce, and the last one, which is pretty good in regards of API and features, makes framerate drop from the standard 60 to about 14, even if you just initialize it, and do a standard update/draw ( = you haven't added ANY controls to be updated/drawn).

    so there isn't really a choice - you either somehow suffer through the learning curve of Neoforce, or you program your own. I'm still not sure which one is going to be more time-consuming.

     



  • [quote user="Renan "C#" Sousa"]Because if it's free, well, you get what you paid for.[/quote] 

    reply on forums recieved, problem solved. seems like there IS something that could be considered to be kind of a documentation - the download package contains source of official neoforce demonstration app , which, though lacking good comments, is pretty self-explanatory. The problem is that source to this app is dug&hidden deep in subfolders, and there's not a single sentence that would mention it is there, even it's name (and names of the files in it) is completely unsuggesting as to what it is... Looks like it will take much less time to learn to use it, than to program my own, after all...



  • Can't help but wonder if I'm the only one experiencing some massive values dissonance here.  I read this and I think, "what's wrong with the OP, that he freaks out so badly about not having documentation for this library?"  Maybe it's just that I'm used to Delphi, which was designed specifically to be easy to read, and most "documentation" issues can be solved by UTSL.  (Which is generally better than documentation anyway, because it can't get out of sync with the source code, by definition.)

    On the other hand, I would never, ever, under any circumstances even consider developing with a library, free or commercial, that did not come with full source.



  • @SEMI-HYBRID code said:

    @tster said:

    Really, what are you expecting from Czechoslovakia?
     

    thank you, but we're two separate countries* for about 21 years by now, and besides that, Tom Shane isn't really czech name. it's more likely that it is on .cz because it was cheaper than .com or the likes

     

    * czech republic , slovak republic (slovakia) , learn the difference already, you're programmers, you're supposed to be able to learn fast

    Things were a lot simplier when my globe just said "USA" on one half and "USSR" on the other.

    Sure we won the Cold War, but at what cost? At what cost!!



  • @blakeyrat said:

    Sure we won the Cold War, but at what cost? At what cost!!
     

    you were the ones who wanted to bring freedom unto the world, so face the consequences now. but either way, czechoslovakia was never part of ZSSR, we just had puppet governement, and later, when this governement started to do things which ZSSR disliked, they sent army and occupied us for 30 years. but we were STILL (officially) a separate, sovereign country, through the whole process.



  • @Mason Wheeler said:

    On the other hand, I would never, ever, under any circumstances even consider developing with a library, free or commercial, that did not come with full source.
     

    to me, on the other hand, one of the primary points of using a library is not having to care about its source (as long as it works properly).

     

    additional point: if you've ever done at least a smallest bit of any programming, you've already used tons of libraries to which you don't have source. what do you think an operating system is? just a ton of libraries ;-)



  • @SEMI-HYBRID code said:

    @blakeyrat said:

    Sure we won the Cold War, but at what cost? At what cost!!
     

    you were the ones who wanted to bring freedom unto the world, so face the consequences now. but either way, czechoslovakia was never part of ZSSR, we just had puppet governement, and later, when this governement started to do things which ZSSR disliked, they sent army and occupied us for 30 years. but we were STILL (officially) a separate, sovereign country, through the whole process.

    Yeah, but you still ate borscht right? And painted red stars on all your trains? Same deal.



  • @SEMI-HYBRID code said:

    @Mason Wheeler said:

    On the other hand, I would never, ever, under any circumstances even consider developing with a library, free or commercial, that did not come with full source.
     

    to me, on the other hand, one of the primary points of using a library is not having to care about its source (as long as it works properly).


    Yeah, that caveat's the whole point. How many libraries have you ever used that work exactly right, out of the box, and don't require any bugfixes, customization or extension of any kind?

    additional point: if you've ever done at least a smallest bit of any programming, you've already used tons of libraries to which you don't have source. what do you think an operating system is? just a ton of libraries ;-)

    ...which is why I hate programming for Windows.  When something goes wrong at that level, there's no way to trace into the system libraries and figure out what's going on.



  • @Mason Wheeler said:

    ...which is why I hate programming for Windows.  When something goes wrong at that level, there's no way to trace into the system libraries and figure out what's going on.

    Just use an easier API. If you're using .Net and "something goes wrong", it's pretty much guaranteed to be your own damned fault.

    I will agree that the old school Windows API is a nightmare, though. The solution isn't to switch to Linux, but to use a better API.



  • @blakeyrat said:

    The solution isn't to switch to Linux, but to use a better API.
    Switching to Linux is better for your soul.



  •  @Xyro said:

    @blakeyrat said:

    The solution isn't to switch to Linux, but to use a better API.
    Switching to Linux is better for your soul.

    Linux is Open Soul Software now?



  • @SEMI-HYBRID code said:

    I mean, dammit, this is the moment I fully realized the truth of "Bad documentation is thousand times better than none".
    A thousand times zero is still zero

    </kidding>


Log in to reply