Docs
Community Forums/Monkey2 Talk/Docs
| ||
| This came up in language features. I think it deserves it's own topic. He could always put a wiki thing up on the site and the people who have sponsored his patreon thing can add/edit stuff in there, obviously, there will need to be a "verify" post thing so it cannot be smashed to bits by a huffed user... Bet it would sharp stack up with examples and what not! That would indeed take away the "awful docs" whinge that happened when BMax was released! Dabz I think there should be an online docs system, probably more of a hub. We as users should be able to edit and create content: tutorials, function examples, etc. Dabz suggested a "verify" post thing. I think that the solution should be to unburden Mark from such things and leave that to the community. Although he should still be able to overrule anything he wishes (kind of an admin). There could be a voting system in place that allows members (any registered monkey user) to vote. PHP has something in that direction -> http://php.net/manual/en/function.urldecode.php edit: sorry Dabz <3 |
| ||
| I think that the solution should be to unburden Mark from such things and leave that to the community. Well yes, I was thinking in terms of some trusted users moderating said wiki thingy! ;) Dubz suggested a "verify" post thing. Hehehe, what is it with the monkey forum making everyone spell other peoples names wrong!?! :D hehehe Seriously though, if we can knock docs up ourselves, then half the battle for the new product is won IMO!!! Dabz |
| ||
| Yup some type of user supported documentation system would be cool. Stack Overflow always is a favorite of mine for user generated style solutions. Putting the power of the crowd to work is always useful. |
| ||
| It was years before I learned About certain features in blitz basic with types and functions. I am Hoping for complete and clear docs/examples this time. I hope now that there is a donation system that a lot of things improve. Go blitzresearch! :) Edit: maybe pay someone to make docs? |
| ||
| If MX2 has the same BMX code-stile (=bbdoc inside source code) it will be a *job* of Mark (or who writes the code) to make clear documentation. At this point the best solution is to have both: the 'inner' (maybe basic) doc and ALWAYS a link to an extern system (wiki or whatelse) to find more informations (not based on some 'magic' in the IDE, just a pure, plain, link!) In BMX documentation is local. Only with hacks is possible to link to the online-documentation (and there are different solutions, the 'official' manual, some wiki and so on). So I hope - ONE only place to find/add/explain things; - adding info/code etc (as in the current manual section for BMAX); - the possibilty to download it and make it local (if net connection is not available or capped) Cheers |
| ||
| A git for examples / tutorials / docs (in markdown format for generating static pages from) would be nice. Then it would be easier for people to contribute, plus find older versions of examples and docs for older version of m2. |
| ||
| +1 Extensive and up-to-date documentation with plenty of useful examples should be one of the things to focus on. Definitely something the community could help a lot. I hope there will be community-supported online docs with comments and version reference, at least from 1.0 onwards. |
| ||
| I always thought MSDN (and to some extent, php.net) to be a pretty good example of documentation. The problem with php.net's approach as I remember it is that examples end up being woefully out of date as the language breaks them or has other unwanted behavior, and top comments can often have old/outdated examples as well. A "graduated" format resembling MSDN but with the social features of a wiki or other site for individual pages could work well -- having users be able to "graduate" from the comments section to the main article/wiki section rather easily, but displaying the main article first. I wonder if there's a Wiki fork that shows the main page and the talk page simultaneously in a split view... |
| ||
| A fancy online docs system with community support is a project unto itself. Are there any ones working right out of the box that BRL could use ? |
| ||
| MediaWiki and others.... |
| ||
| I'd definitely contribute code examples to a wiki. Maybe not on a daily basis, but here and there! If everyone else was chipping in like this, we would quickly build up a brilliant community resource. Maybe Mark, you could incentivise user contributions in docs, modules, etc by offering some form of rewards. Eg forum badges, front page banner/feature space. You could even add gamification to user accounts so you gain experience for activities. People heart your posts, gain XP. Make contributions to the wiki, gain XP. Add games to the app list... XP. You could then level up and gain special icons/titles/etc on the forum. But that's a lot of work, bare minimum need a decent wiki for docs! |
| ||
| It takes so long to make a Large number of examples. I had times when it took me 6 hours to finish one example. I think not a lot of people wil want to spend that much time making docs and code examples. Also becourse the language is more complex it wil mean that only exerienced coders would be able to create good docs. When i started in monkey 1 I was doing procedural examples and when I got more experienced I was able to create more advanced code. I have not mastered the language at all yet imo. I have not seen a lot of new tutorials be made since I bought monkey. I expect we should not count on the community creating the docs. There would be a lot more tutorials and code on the forum if there was motivation for that. If al Goes as i expect then I am going to create a code example blog for mx2 on my Own and make Some video's on YouTube. I myself think I would not be good enough to edit a wiki for mx2. I would place comments at the most. Blitz basic 2 and + and 3D had the best documentation so far. Though not every feature was described. I have not looked at blitzmax yet but I read it was not good. Monkey has the forum going for it. Lots of experienced people and almost every problem gets solved. I was surprised once when I looked at this language called playbasic. It had a huge amount of examples and good docs. I almost bought it but discovered it did not work like it should when I tried it. Buggy key input. The docs and examples and features on this one are a good example of what you Need to get started with a language. Maybe look at that for ideas? I also remember having fun with amos and amiga blitz many years ago. Had enough information to be able to get programming. This was before the internet. Anyways. Think of the less experienced/younger people that Need to leArn the language. |
| ||
| Anyways. Think of the less experienced/younger people that Need to leArn the language. Well that's the point, when I'm suggesting examples, I mean in a sense where there's a basic example of how to implement, say, keywords, syntax and functions... Not "how to build a platformer", that sort of stuff falls under "tutorials", which is different again, and should be divided under beginner, intermediate and advanced sections! Dabz |
   |