This topic contains 21 replies, has 9 voices, and was last updated by 
abakobo
2 years, 2 months ago.
-
Posts
-
ok, I needed a filled 2d polygon.
so help gives me canvas.DrawPoly( vertices ) which is fine if you ‘know’ what this means.
I then did a quick search on the forum and there were a few very complex examples. Nothing simple or straightforward
Yep. I know I need an array of vertex points. but again you have to know what that actually mean which is not really very helpful.
It would have been great to have a very simple example that could be copied and pasted.
Did I achieve what I wanted – yes. But I had to go back into my own code and search out how on earth i did it for another project.
Mark. You really need to up the help. Make it proper helpful. Every command should have a clear – CLEAR and SIMPLE example.
Otherwise Monkey2 is not going to win many new or learner programmers.
The description for many classes says only “The *** class” – for example:
– The ProgressDialog class.
– The TreeView class.
– The HtmlView class.
– The CheckGroup class.
– The TableView class.Would be nice to have at least a minimal description for what a class or another type
is used for.
For the GUI elements, it would be nice to better see and separate what is a layout element
and what is actually a widget/gadget. Maybe add “(layout)” or something like that in the
short description, so we can see that in the overview.Additional to small examples, I would also add some images to it. A small image of a
button, listbox, scrollbar – maybe with different styles applied.
Adding some visual graphics and screenshots, logos for libs, etc. may make it
a better experience (for the eye), in my opinion.I’d say examples like this, are very important to create new patreons, but equally Mark doesn’t have the time or rather he would be better doing more complex things!
What’s the best way to help improving the documentation, Mark?
Make a copy on github, add/edit monkeydoc, and submit it on github?
Add help to latest master, or is it possible to access/fork the
latest developer branch?1. When someone says that he wants to help make the docs, I wonder if you have enough skill?
2. You can clone any branch in the repo but Mark dislike to merge anything.
3. What about FAQ section in this forum? It is closed but can be opened to fill by community.
4. I prefer to read articles about using mx2 on doing real things instead of ‘plain’ lang reference.
Let’s leave docs for Mark (with requests for him to improve some parts when needed) and write usage examples.
> Let’s leave docs for Mark
That’s why I’m asking how the international community can help.
Most classes are undocumented, there are only very few documented classes.“Let’s leave docs for Mark” did not help. Most stuff is still undocumented!
Best thing would be if many people work together. Mark could check the
spelling and mistakes, but at least people could help.
Or, Mark gives direct access to the sources to 5 to 10 people, to enhance
the docs. Let’s call it ‘documentation team’.Docs need improvement, and many docs are not written yet. I hope Mark
can give a clear answer how he would like to change that and how we
should collaborate – how the users can help.
Github, with different branches, may not be the best option for
collaborating documentation management.Everybody of us has to read the sources to find out what all the
undocumented classes actually do. After finding it out, it would
make sense to actually contribute that finding to the official docs.
After a while of guessing, we could have documented classes, so the
next generation can read the docs instead of reading the sources,
trying to understand the structure, inheritations, and guessing
what it should do.I really dont understand Mark’s reticence to engage with the communoty and get help with documentation, guess he just doesnt like money, cause for sure the way the docs are now it must be putting off droves of people…
Best thing would be if many people work together. Mark could check the
spelling and mistakes, but at least people could help.
Or, Mark gives direct access to the sources to 5 to 10 people, to enhance
the docs. Let’s call it ‘documentation team’.We can fork the dev branch and modify only the monkeydocs then Mark can make a pull requet himself if he likes the things we’ve written.. so we manage ourselves the direct acces.. by not modifying code we can update our fork easily.
I had started to list some undocumented things a while ago:
language:
———extention keyword
where keyword
array tips and syntax for initialisation (1,2,3) multidim ((1,2,3),(7,8,9))?
protected private public, shared things when in the same .monkey2 file
(& virtual?)infos on methods onrender and onwindowevent are not correctly created during doc building (seek that kind of ‘gaps’ and correct doc code)
? and ‘ternary’ conditions “if blah ? blah else blah”
[0] -> dereferencings syntax, are there other ways to dereference?
mojo:
—–OnBlah stuff mx1 style is now implemented as ‘signals’ in AppInstance
mojox:
——
mojox in general?c2mx2:
——
is not copying the api’s ///docs to #rem monkeydocs, can clang return ///docs so c2mx2 copy it?sharing such a list somwhere would help us to make a todo list. and modify/pimp the docs
I’ve created a github organization: https://github.com/mx2DocsCommunity
I invited the people who said they want to be involved in a community doc work (and I knew their GitHub Name (invited as owners)i.e.: nerobot, AdamStrange, peterigz (I didn’t search for long though))
If you think it’s a good idea to work on a fork to add our #monkeydoc modifications and later let Mark do what he wants merging, accept invitation or ask for an owner/member invitation to start workin together. If Mark doesn’t like it we’ll still be able to build those docs and share it.
Of course Mark if you want to be invited you’ll be welcome but the aim of this fork is not to take your time and work on our side so I didn’t invite you.I created a ‘docsWork’ branch based on the develop branch. If we work only on that one (or other new ones based on docsWork) and not on master,develop,scratch branches we’ll be able to continuously update from the original dev branch without too much hastle.
Added a DocsTODO.txt file for sharing things we think should be done. It’s more or less the list I put on the previous post for now.If you think it’s a good initiative please tell and I’ll create a new topic on the forum to announce it and invite people to participate..
Docs and BRL, this kind of reminds me of … 1 2.
Working on something which might only get live doesn’t sound motivating. How do people easily access these docs? (How) will they be merged with new docs from Mark? How about something like BlitzMax’s WikiBook? You could create/update/consume this nicely (your own content + export of Mark’s docs + references to original docs + links to users’ external content). Once there is substance and Mark hasn’t improved the docs on his own, it might make its way into the docs. If not, at least it’s available on the net.
Ideally Mark would offer more docs and there would be a strategy plus communication on how to address the situation best in the future.
Working on something which might only get live doesn’t sound motivating
I understand, the idea here is to help Mark having a nice OOB doc. One that can be used with F1 and that could make mx2 a ‘solid’ set. Also a wiki is something that will only be live and importing it later to the ‘#rem monkeydocs would need a lot of work later.
How do people easily access these docs?
Ultimately by pressing F1 or in Help>Browse docs. During WIP by importing the modules from github and build docs. May be it would be better to work on a fork of the master branch instead of dev branch for it to be more easily used by people who just want to use it.
It could also be generated by a CI so it’s always visible up to date.(How) will they be merged with new docs from Mark?
-(How) That’s what a git is for. It’s the one of the most used tools for merging that kind of things.
-Mark accepts things, he’s put Ted2Go in the distro, he’s accepted pull request but made the change by himself, he’s been putting bananas in the repo when he thinks it helps, sometimes two days after a suggestion/request it up on github dev branch and he doesn’t say anything BUT do it. If we do a good job I think he’ll probably merge, it’ll not be touching one line of code. IMHO it has to be done by big batches. He is asking for community work in some ways after all.How about something like BlitzMax’s WikiBook?
That would be great too! It seem to be well structured and very educative. For the integrated docs I’m more thinking of something with a lot of little examples for of a lot of occurrences. But a pimp of the language reference too, witch should be educative in some sense.
your own content + export of Mark’s docs + references to original docs + links to users’ external content
Great too, but some things are missing in the original docs now.
Ideally Mark would offer more docs and there would be a strategy plus communication on how to address the situation best in the future.
It’s clear that Mark is not really into presentation/docs/communication&marketing. By trying to help, adding infos he gave us on the blog&forums but are not put in the docs, we do what he has no fun with. This can be a winwin if some of us like to do it.
I honestly don’t see much issue with the API docs, but you need rather more than API docs
Its more about how a module should or could be used, this kind of documentation isn’t the type that you could put in the auto doc comments.
As well as some introductory text – a selection of examples are vital – ideally ones that can be pasted into an IDE and “just work”
I honestly don’t see much issue with the API docs, but you need rather more than API docs
I see some. Chipmunk is empty, other modules are empty, even in mojo there are gaps and strange doc builds.
The auto docs of the language reference could benefit of some adding too. It’s totally unsearchable. Even with “varptr site:http://monkey2.monkey-x.com/monkey2-docs/” on google you’ll have nothing. And some keywords are missing.
It would need a keyword index and a better table of contents IMHO.
For me, someone who’s used to programming and to use integrated docs should be able to understand monkey-2 with the autodocs and basic examples only (bananas).Its more about how a module should or could be used, this kind of documentation isn’t the type that you could put in the auto doc comments.
I think both have to be done. Nerobot has created a wiki and started some writing. People who want to explain how some modules work and write basic mx2 tutorials are welcome there I think.
I have learn monkey2 mechanics with some monkey-x tutorials in some ways but mainly with the mx2 language reference and module section + bananas and of course this forum/blog.With github, people who find that an mx2 doc is unefficient, is lacking something, would need a little example, can post an issue or modify if he/she has motivation. Unlike original monkey2 github, it would have to be very issue posts oriented.
The quality of integrated docs can profit of that. There’s the problem of no copy-paste still but docs can be opened in a normal browser anyway.Just to refer some docs Mark recently added
https://github.com/blitz-research/monkey2/commit/bedec805fd49eb729a30a792649d73a977f738ea
What I really would like to see is MORE examples: from the ‘basic’ one, to the complex one. Reading it, changing it is a good way to understand what commands/functions are for.
Technically at least 3 examples for arguments are needed – the basic one as simple introduction, the other to cover more features/special cases.
A wall of text – in some cases – is not-needed AND can be (via wikibook or other solutions) provided in future.
You must be logged in to reply to this topic.