This topic contains 12 replies, has 9 voices, and was last updated by 
abakobo
2 years, 3 months ago.
-
Posts
-
Every command broken down with working examples, very visual approach. definitely NOT perfect.
But 100X better than what you are offering.
If you want to get users involved with this you need to up the documentation somewhat?
I think maybe Mark has his hands full with the project itself. Another approach would be to create a Community Documentation Project. I propose that we maybe set up a Wikipedia-like site where trusted users can commit changes to any particular documented code or, add new pages based on Marks commits on Git and the Articles on his Blog. So far we can take most of what we have from this website for Monkey 2 and maybe a little info from the Monkey 1 the Docs since they’re kinda identical syntactically.
That way Mark can focus almost exclusively on Monkey where as we can keep the docs as descriptive and informative as we can, thus allowing newer users to get started quickly.
Who’s up for this? I am.
Adam, I’m not sure the comparison is fair/valid.
Yoyo Games probably have an employee dedicated full-time to writing documentation for their Gamemaker product. And they can afford it: Gamemaker is not open source and the Pro and Master editions are $149.99 and $799.99 respectively. Plus it is listed on Steam and so benefits from that exposure.
BRL is basically a one man show, and Monkey 2 is an open source project. Therefore it survives purely on the generosity of contributors via Patreon and Paypal donations. And Mark’s time is limited.
That said, I agree documentation is very important. So, aside from cash donations, maybe the best way people can contribute to Monkey 2 is via documentation, whether examples, tutorials, API references, etc. There are already docs available, though scattered in various places such as the official Monkey 2 docs, forums, youtube, github and other websites.
Maybe we do need a centralized documentation aggregation point? (ie a Wiki, as scurty suggests)…
I’d imagine that we could implement this quickly by pretty much copying the current Docs available and just updating the HTML/JS, however this would be very difficult beings how the Docs are generated by mx2cc. I’ll take a look and see if there’s anything reusable for this as a starter template. Word later…
The main doc weakness is IMO the language reference. Because some part of it are on the blog or even in forum answers.
A wiki would be a great community initiative. I’m in. I already made some little examples about externals and other things like that.
And making such doc is probably the best way to learn/master the language.
My dream doc is a doc with as much running examples as possible..@adamstrange I think the point could have been made in a more diplomatic manner…
that said the documentation is a bit on the weak side, just documenting an API is sadly seen as enough (by all too many projects), but Mark is working on his own, and simply does not have enough time to document things fully.
I’ve made a handful of posts on the document comments, and I definitely think a Wiki (an official one) is needed, where each command gets 2-3 simple examples, and all the things that come out in blog and forum posts can be collected in one authoritative place.
Yes, I see this thread being made as an attempt to humiliate and embarrass(it may not be true but thats how I see it.) but I don’t think it’s a fair comparison or a good idea due to the way monkey2 is being worked on. I am also sure Mark knows it’s weakness but has to decide between working on the language or working on the documentation. So, the question is what should he focus on? as it stand We need programers to step up and attempt to help either by creating their own tutorials and or good documentations instead of putting it down. I am not a good coder or a good documenter. I don’t even document my own stuff but I am willing to help, not much, but can offer my help if useful.
The major lack of the current documentation in Monkey2 is the ‘module’ section (mainly the ‘extern’ ones): take a look at litehtml and see. You can find only a generic
More information about litehtml can be found at http://www.litehtml.com/
Not a description, not a tutorial, not a clear way to use it.
And following the link I get lost… I still haven’t found a proper documentation! Worst & worst!Core-language features are in-source coded, so in time they could be better (and there’s something – very basic – at the moment): I don’t think this is a problem.
To start, we should Document the Standard Library since it’s the simplest, and then move on to Mojo, then Mojo X. As such we can focus on the other modules that exist by default at the moment.
And as for the Downloadable Modules, I guess we’ll have to just add Documentation for those unless the developers of said Modules have their own Documentation ready. I’ve noticed Pyro by Playniax has a great start on Docs already so we can leave that one out for now. (Unless Playniax Might want us to help too. xD)
So should we make a Git repo for this? Or just a website where you make an account, request to help write/update Documentation as needed. This should be requested from Ted2 using ‘litehtml’ like the normal.
So far the only reusable stuff I’m seeing in the current docs source directory are just CSS files and a JS Tree. That literally seems to be most of this website’s code just duplicated for ease.
I’m pretty good with HTML and CSS and some PHP. But I’d rather use Git or WordPress.wow wish i could help, but i lack experience, but this sounds great good luck! this is what opersource is truely about!
Very nice idea to manage docs & samples by community !
I would say ok, but only if they are properly integrated and referenced from a combined/unified centre. that is not online based.
Otherwise all you end up with is a dumping ground of brilliant things, with no logic or order. so it becomes more and more unusable.
Another thing that really should be the main priority is either fixing or completely dumping the mini html view for help. The reason I say this – NO CUT/COPY OF TEXT. That alone should get someone fired. And free should never mean cheap or hacked – which is exactly the way ‘edit locked’ help systems are!
If we were being really realistic here we would gang up (preferably with pitchforks and lit torches) and burn htmllite and use the standard editor to format and display the help text – that is the most logical was of doing it?
Online based is sometimes very usable to me.
For me that kind of wiki is a great kind of resource:
http://wiki.osdev.org/Main_Page.
This example is covering one of the most difficult thing to do in development/coding and is still readable.IMHO a wiki is the way to go for tutorials, language reference, beginner manual, specific manuals…
Modifying/adding the code of ‘#rem monkeydoc’ to get valuable infos is a bit problematic because it would need to fork mark’s repo and constantly update his work to get community work usable with F1. Though doable with some manual commits sometimes?
Or maybe linking F1 search to another base manual.The example of litehtml is one of the worst situation because there is no in-code ‘///’ docs.
For chipmunnk there is some ‘///’ docs doxygen style but c2mx2 is not copying them to ‘#rem monkeydoc’. I suppose it’s possible but don’t know how clanglib works.
You must be logged in to reply to this topic.