Better Documentation Needed
Monkey Archive Forums/Monkey Discussion/Better Documentation Needed
| ||
| I'm sure this is coming, after all Blitzmax has some of the best documentation of any language or API I've ever seen. But I have to imagine that Monkey would be a rather difficult nut to crack for inexperienced coders. I'm a (very) experienced programmer with a year of blitzmax under my belt and I can get all I need to know from a few source files, but for beginners I imagine that it would be quite difficult to get any sort of grip with the object oriented structure of Mojo, etc, with the docs I've seen available. Perhaps this is just something that will emerge over time, but if Monkey is an attempt to position something for beginning coders, I really think it's rather dropping the ball in this regard. From my perspective, it's obviously far preferable to learning six (or whatever) languages on separate compile targets :D |
| ||
| Yup. Now the question is, who has the time to write better docs? |
| ||
| Maybe there could be some sort of community doc project with each involved person taking a little chunk of the language to get very familiar with and document. I don't know where the blitz docs on wikibooks came from but because of that, blitzmax has some amazing documentation. |
| ||
| blitzmax has some amazing documentation People used to complain about blitzmax's docs all the time so the wikibooks page must be doing something right, Maybe someone could set up a wikibooks for monkey? |
| ||
| While I agree that is it kind-of lacking documentation for a beginner. Monkey is a very small language. In less than a month I became familiar with most, if not all, of it's abilities. Someone who's never made games and is going into game making should probably have some experience with other sorts of programming and common data structures before attempting it. That said, I have taught and am still teaching a person who had three-to-four months, college, experience with Python and VB.NET. And was very unfamiliar with common data structures. It took them a couple of days, but they learned a fairly large portion of the language, common data structures, and understood enough to make little game demos. Explaining OOP to them has been extremely difficult. However, that in my mind has to do more with theory and once that's understood, it's all about practicing. In short, as far as I can tell, Monkey is not hard to learn. Even for those with limited programming experience. What's difficult for most people is understanding OOP at it's core. Which has, really, nothing to do with Monkey itself. A little off-topic, but I've been and still am writing a free online e-book, of sorts, for beginners to learn these things and hopefully game development by the end. If anyone is interested in contributing, the link is in the signature. E-Mail is in the profile here. |
| ||
| There are some good tutorials on it. I've learned a fair bit from reading the source to the Asteroids game published here. But I would love to see some more source-- I guess that's the price for getting in on the ground floor. |
| ||
| Explaining OOP to them has been extremely difficult. However, that in my mind has to do more with theory and once that's understood, it's all about practicing. I had the worst time with OOP, until I finally realized that it was a simple concept that I already understood. I don't know why my instructors made it out to be more complex than it was. Re: more source code Yes, the docs need source for almost every example. But if you want more code examples, here's a simple platformer game from therevills. http://monkeycoder.co.nz/Community/posts.php?topic=449 |
| ||
| zoqfotpik as ive said long time ago about monkey now other people are waking up monkey was made for blitzmax users at first place. other people should struggle and ask silly question just to start to understand monkey. |
| ||
| monkey was made for blitzmax users at first place. Wrong! Monkey was made because there was a need for a cross platform blitz-like language for mobile platforms also. Yes Blitz users had been asking if there would be, well some, but just as many that were asking for a Monkey :) others couldn't care less. Mark made a tactical decision, seeing that mobile|tablet dev was not going to go away, came up with a wonderful Monkey to play with. :) Oh! I don't know if you knew this but trial and error, not asking on the forums every time something doesn't work, and actually problem solving yourself; Programming, will get you further and develop your skills more than getting everything answered for you. By all means ask your questions because they will get answered if a kind soul, many of them around, pops by to check the forum, just try and make sure you have exhausted your current knowledges' mojo before firing off. No question is Silly, really, except for when it is obvious that if you put half an effort in yourself to answer it you would have found the answer. Bye! |
| ||
| I think the real question about the docs would be for whom it is for :) I think or guess that most developers here has a good grasp on programming already. Meaning that looking in source, the docs as they are, the forum, or the language reference is enough to get by. And it seems to me Monkey is not (yet?) aimed at beginners. Tough imo I think it one day will appeal to beginners if there is a way to help them past the initial road-block. In the end when I want to make something fancy I will want to start to use external frameworks made by the community. Or code from these forums. Most of which has little or outdated documentation and examples. Personally I would like a system or section of the site so that documentation & examples can be added for both to official modules and to user modules. I'm not just sure a wiki would be the right thing, they usually tends to be less than fun to update once they reach a critical size. I tend to write documentation in the code, yet there is no easy way to get it out into a structured & searchable format - would be cool if monkey-trans could generate html or xml documentation, the system that exists is not too bad imo, with a little extra work I think it could be excellent. Not that it is a difficult thing to do oneself, it is just that the point of such thing would be to make it "official" so everyone uses the same doc system. @Amon, I agree. Just ask, I think most in this community assumes the question has a positive intention. |
| ||
| hi, Interesting thread. in my opinion its very easy for everyone, no matter which skills and progress and the docs are just great. The starter docs even helped two of my friends who never developed so far, to get their thoughts into code. now they are selling some apps on the stores. By the way as a programmmer, its the normal way for me to develop my solution myself and its always fun for me checking out new ways or languages, libraries or engines and open source. Since monkey supports c code there is much stuff possible.. Well, just my opinion. I wish you all a happy new year :) May all your dreams , wishes and plans get realised 2012 ;) |
| ||
| sorry ive pressed on post 2 times over.. ....please cancle this..... |
| ||
| sorry ive pressed on post 2 times over.. ....please cancle this..... my internet connection is slow.. sometimes |
| ||
| There should be an online docs section. Ive allready passed the begginers level, I only care for those who hadnt. Amon Wasting 90% of your energy understanding the basics of a software is not the right way to learn.. Function SquareToSquareIntersection(Sqr1X#,Sqr1Y,Sqr1XSize#,Sqr1YSize#,Sqr2X#,Sqr2Y,Sqr2XSize#,Sqr2YSize#,CornerSize#=5) 'Wont Work if the two squars are on top of eachother in some cases. 'this function is for detecting first encounters mainly rem ______ | | | __|___ |___|__| | | | |______| end rem 'cornersize is for detecting square corner collision 'Flags local ColUpLineFlg% Local ColDownLineFlg% Local ColLeftLineFlg% Local ColRightLineFlg% 'Checks Object1 Lines Collide With Object 2 if HorizLineOnSquare(Sqr2X,Sqr2Y,Sqr2XSize,Sqr2YSize,Sqr1X,Sqr1Y,Sqr1XSize) =True Then ColUpLineFlg =True 'Up Line Check if HorizLineOnSquare(Sqr2X,Sqr2Y,Sqr2XSize,Sqr2YSize,Sqr1X,Sqr1Y+Sqr1YSize,Sqr1XSize)=True Then ColDownLineFlg=True 'Down Line Check if VertLineOnSquare(Sqr2X,Sqr2Y,Sqr2XSize,Sqr2YSize,Sqr1X,Sqr1Y,Sqr1YSize) =True Then ColLeftLineFlg=True 'Left Line Check if VertLineOnSquare(Sqr2X,Sqr2Y,Sqr2XSize,Sqr2YSize,Sqr1X+Sqr1XSize,Sqr1Y,Sqr1YSize) =True Then ColRightLineFlg=true 'Right Line Check 'CollisionMeasure local ColMeasX Local ColMeasY 'Determain if ColUpLineFlg=True Then 'Check UpLine if ColLeftLineFlg=True Then ColMeasX=(Sqr2X+Sqr2XSize)-Sqr1X ColMeasY=(Sqr2Y+Sqr2YSize)-Sqr1Y If ColMeasX<=CornerSize and ColMeasY<=CornerSize Then 'If Square Hit Up Left Corner Return SqrCol_LeftUpCorner Else if ColMeasX<ColMeasY Then Return SqrCol_LeftLine End if Else if ColRightLineFlg=True then ColMeasX=(Sqr1X+Sqr1XSize)-Sqr2X ColMeasY=(Sqr2Y+Sqr2YSize)-Sqr1Y If ColMeasX<=CornerSize and ColMeasY<=CornerSize Then 'If Square Hit Up Right Corner Return SqrCol_RightUpCorner Else if ColMeasX<ColMeasY Then Return SqrCol_RightLine End if EndIf Return SqrCol_UpLine 'Square Hit Up Line End if If ColDownLineFlg=True Then 'Check DownLine if ColLeftLineFlg=True Then ColMeasX=(Sqr2X+Sqr2XSize)-Sqr1X ColMeasY=(Sqr1Y+Sqr1YSize)-Sqr2Y If ColMeasX<=CornerSize and ColMeasY<=CornerSize Then 'If Square Hit Up Left Corner Return SqrCol_LeftDownCorner Else if ColMeasX<ColMeasY Then Return SqrCol_LeftLine End if Else if ColRightLineFlg=True then ColMeasX=(Sqr1X+Sqr1XSize)-Sqr2X ColMeasY=(Sqr1Y+Sqr1YSize)-Sqr2Y If ColMeasX<=CornerSize and ColMeasY<=CornerSize Then 'If Square Hit RightDown Corner Return SqrCol_RightDownCorner Else if ColMeasX<ColMeasY Then Return SqrCol_RightLine End if EndIf Return SqrCol_DownLine 'Square hit down line End if End Function In this function that ive made you can see i even added a graphic presentation just to visualise what the function does. |
| ||
| There should be an online docs section. Ive allready passed the begginers level, I only care for those who hadnt. Amon Wasting 90% of your energy understanding the basics of a software is not the right way to learn.. |
| ||
| There should be an online docs section. Ive allready passed the begginers level, I only care for those who hadnt. Amon Wasting 90% of your energy understanding the basics of a software is not the right way to learn.. |
| ||
| There should be an online docs section. Ive allready passed the begginers level, I only care for those who hadnt. Amon Wasting 90% of your energy understanding the basics of a software is not the right way to learn.. |
| ||
| There should be an online docs section. Ive allready passed the begginers level, I only care for those who hadnt. Amon Wasting 90% of your energy understanding the basics of a software is not the right way to learn.. |
| ||
| There should be an online docs section. Ive allready passed the begginers level, I only care for those who hadnt. Amon Wasting 90% of your energy understanding the basics of a software is not the right way to learn.. |
| ||
| There should be an online docs section. Ive allready passed the begginers level, I only care for those who hadnt. Amon Wasting 90% of your energy understanding the basics of a software is not the right way to learn.. |
| ||
| There should be an online docs section. Ive allready passed the begginers level, I only care for those who hadnt. Amon Wasting 90% of your energy understanding the basics of a software is not the right way to learn.. |
| ||
| Wasting 90% of your energy understanding the basics of a software is not the right way to learn Maybe you should change the way you view what wasting your time is? Remember that Programming is not only about understanding and writing code but also the state of mind you are in. If you consider it wasting 90% of your time learning the foundations of what will be your knowledge of a certain software|programming language|whatever, then you'll never have build that foundation in to something solid that will work practically across the board, not just for your coding but for your own mind. Change the "wasting 90% energy" to "Investing 90% of your energy" in to getting those foundations stable, solid and ready for heavier work. :) Another thing to consider is that if you are going to let your knowledge rely on some docs which you think are not there what happens if the docs you need never materialise? Will your learning stop? Will you not progress? |
| ||
| Amon I must say I Love your approch in :) Waisting my Energy I ment that taking out energy on simple things that if explaind right would not take more then a couple of minuts. I love learning. but not breaking my head Im not waiting to be fed as you see I progress.. Cheers And Happy new year! |
| ||
| You talk about documenting code, but it took me minutes to work out what you're trying to do because of your "corner" thing. If I'm right, this is what you're doing (I haven't tested it): Function SquareToSquareIntersection(Sqr1X#,Sqr1Y,Sqr1XSize#,Sqr1YSize#,Sqr2X#,Sqr2Y,Sqr2XSize#,Sqr2YSize#,CornerSize#=5) ' die if it didn't intersect at all If Sqr2X + Sqr2XSize < Sqr1X Or Sqr1X + Sqr1XSize < sqr2X Or Sqr2Y + Sqr2YSize < Sqr1Y Or Sqr1Y + Sqr1YSize < sqr2Y Then Return False ' check corners If Sqr2X + Sqr2XSize < Sqr1X + CornerSize And Sqr2Y + Sqr2YSize < Sqr1Y + CornerSize Then Return SqrCol_LeftUpCorner If Sqr2X + Sqr2XSize < Sqr1X + CornerSize And Sqr2Y > Sqr1Y + Sqr1YSize - CornerSize Then Return SqrCol_LeftDownCorner If Sqr2X > Sqr1X + Sqr1XSize - CornerSize And Sqr2Y + Sqr2YSize < Sqr1Y + CornerSize Then Return SqrCol_RightUpCorner If Sqr2X > Sqr1X + Sqr1XSize - CornerSize And Sqr2Y > Sqr1Y + Sqr1YSize - CornerSize Then Return SqrCol_RightDownCorner ' check edges If Sqr2X + Sqr2XSize < Sqr1X + CornerSize Then Return SqrCol_LeftLine If Sqr2X > Sqr1X + Sqr1XSize - CornerSize Then Return SqrCol_RightLine If Sqr2Y + Sqr2YSize < Sqr1Y + CornerSize Then Return SqrCol_UpLine If Sqr2Y > Sqr1Y + Sqr1YSize - CornerSize Then Return SqrCol_DownLine End Function |
| ||
| I totally agree with Amon about asking questions but at the same time docs that are abstruse to say the least are not helping matters. "Another thing to consider is that if you are going to let your knowledge rely on some docs which you think are not there what happens if the docs you need never materialise?" Amon, I see what you're trying to get across but if this happens-- if the docs never materialize-- it will mean countless hours of hair-pulling frustration for hundreds or thousands of programmers. It will translate into lost revenue for Mr. Sibly, and poorer sales could mean no more blitz products. Like it or not-- my guess is that you are a fairly to very experienced programmer-- software documentation is a huge issue for the people who buy these sorts of languages. It doesn't benefit us for this to be a niche product only known to a few people... or does it? :) Regardless, I think most people would agree that the better documentation we have, the better for everyone involved. Does anyone know who is behind the Wikibooks documentation for Blitzmax? I'd be willing to take a chunk of the API and document it extensively. |
| ||
| Samah the function content wasnt the point. I only wanted to show the sketch. Sure,what you did is much nicer looking and clear. I sure need to improve my coding level (I didnt check your code as well..) |
| ||
| I have made a wiki specifically for Monkey. Anyone that wants to write for it, do as you please. I got the GeSHi syntax coloring plugin and made a GeSHi syntax configuration for Monkey. I can't say how well it works (colors things) or if some of the colors need changing. If you find/have any issues, tell me. I'll just leave this here, have fun. EDIT: Monkey has an official wiki now, no need for my own... You wrap syntax like this <syntaxhighlight lang="Monkey" line start="1"> code here </syntaxhighlight>or <syntaxhighlight lang="Monkey"> code here </syntaxhighlight> |
| ||
| @GLG... a wiki is a good idea, but like the many BlitzMax's wikis over the years its on a private domain (skyknitters?!) I wouldnt add anything to it, as they all disappeared - so much time and effect wasted. The best place for this kind of information gathering is on wikibooks... http://en.wikibooks.org/wiki/Monkey |
| ||
| I've been running websites since '03. I'm not going away or going to be dropping that domain anytime soon. I also frequently backup my databases, so if I ever did drop it, I would make the wiki's database available in a public download. But, like I said, do as you please. If you don't add anything, fine. If you do, that's fine as well. Also, SkyKnitters was a joke on Sky Net that came from some very bizarre conversation between a friend of mine and me. It's actually meant to take over as the primary domain for all of NRGsoft's non-profit work. Edit: Last note, wikibooks = no syntax coloring. That's no fun. |
| ||
| Its nice of you to offer your time and space for a wiki, but lots of people said the same things as you ("I'm no going away")... :) Yeah it would be nice if wikibooks had syntax colouring, but meh its not the end of the world ;) |
| ||
| I'm really not going away. My web presence has existed since '99 (when I was 8-years old...). Not that I'm aiming to change your mind here, just as a warning though. Publishing to WikiBooks, you allow your content to be copied word-for-word to a commercial product. I don't allow that, except for the code being put into public domain automatically. I'm picky with licenses and don't like WikiBooks' license. |
| ||
| If you intend everything on the wiki to be in the public domain, the Wikibooks licence won't affect you, since they can copy any PD material into a commercial product if they want anyway. |
| ||
| Whoa, no no no. I said, the code is in the public domain. The non-code content written is under Creative Commons Attribution Non-Commercial Share Alike (CC BY-NC-SA). What bothers me is someone taking word-for-word the text written and the code, then using that for profit. If someone wants to take the code and learn from it, fine. However, they don't need the text outside of the code. |
| ||
| Id agree with the documentation for Monkey has some holes in it. Overall its very good and the examples really help explain much of what is needed. The things I see that is a bit of a shortfall is the general syntax referencing. One of the troubles I have had is just looking up the libraries, and language specific functions and what they do quickly. The "language" doc needs to be fleshed out a bit more imho, and a quick ref, when in the editor (like eclipse would be ideal) would help most people. In fact monkey + eclipse with command line completion and auto doc would be pretty awesome :) .. maybe I'll make a template for it one day. Mind you, I think its worth noting that the doc work that has been done is really good and deserves noting that it does provide a great base regardless. For examples Id love to see something like AutoIT's (http://www.autoitscript.com/site/autoit/) help setup where every function has a "cut and paste" running sample - this is probably the very best help documentation I have ever seeing in any programming system. Its very community driven too, which I think Monkey could emulate with its large BB following. Cheers, Dave |
| ||
| where every function has a "cut and paste" running sample Oh, i like that. I've started a little at the wikibooks monkey site: http://en.wikibooks.org/wiki/Monkey |
| ||
| Looks like to me that the learning curve for anything looks like an exponential curve. First stage: depressingly slowly moving up since a lot of things have to come into place. Second stage: things are moving forward faster but still realizing how moronic I was in doing things a certain way as there is a 20x better way to do it (reading code and experimenting on real problems help) Third stage: able to deliver working stuff Fourth stage: enjoying delivering working stuff. Am on a roll. Currently exiting stage 2. |
   |