Mark – thoughts on help (with example)

[Mark SiblyKeymaster]

I try to prioritize docs, so language/std/mojo have precendence right now as I believe these will be the most commonly used. After that will likely come mojox (which as Danilo points out I haven’t even started yet), other ‘pure mx2’ modules, then finally ‘native’ modules (as much as is sensible here).

I’m happy for now with the quality of docs for std/mojo – I consider them to be ‘pass 1’ complete, eg: I think most people can make sense of the DrawPoly docs just fine. Yeah, more docs is always better, but there is still a LOT of stuff that isn’t even at ‘pass 0’ level and that has priority right now. Things will then be further refined in pass 2 etc.

And finally, please, enough with the “Mark! You must do *THIS* or mx2 is boned!” threads. It’s great you have such strong opinions, but please try to understand that maybe not everyone shares them?

[DaniloParticipant]

Thanks Mark! My question was, do you want any help with it, and if so,
what is the best way? Using github for adding/improving docs by external people?

[Mark SiblyKeymaster]

Using github for adding/improving docs by external people?

This is worth a shot I reckon, although it might be an idea for someone else apart from me to handle docs merges as I suspect I’d be ultra-picky about it! Any volunteers (with suitable experience preferably)?

Also, each module should have a ‘samples’ dir with a sample-per-identifier that’s linked to from the docs (so it can open in Ted2 etc). This would be a pretty easy way for people to contribute.

Will have a think about these, but I’m semi-inspired!

[EthernautParticipant]

The main thing I’d like to see in M2’s docs are very simple snippets/examples for all major classes, functions and language features. Searching the forum after “that example I remember someone posted a while ago”  is frustrating, and will only get worse as more people post more often in the forums.

Once more content is in the docs, a better search system would also come in handy (the current one expands the tree view on the side for all results at the same time, resulting in lots of scrolling).

Thanks!

[nerobotParticipant]

Also we can add special section in docs something like “< code >….</ code >” and IDE will produce some additional stuff for it like buttons(links) ‘Copy’ and ‘Open in editor’, so we can operate the code inside of IDE.

And many docs / samples we can grab / porting from mx1 (at least keywords description).

[codifiesParticipant]

The only issue I can see linking samples directly to actual api methods (etc) is that how many examples in rosetta code http://rosettacode.org/wiki/Rosetta_Code wouldn’t fit into this model.

While not all of these snippets may be cromulent its an absolutely invaluable trove as a learning aid.

[abakoboParticipant]

Roseta code is very interresting!

This is worth a shot I reckon, although it might be an idea for someone else apart from me to handle docs merges as I suspect I’d be ultra-picky about it! Any volunteers (with suitable experience preferably)?

I opened an organization on github for that precise goal: merging docs by community in a way that some day it could be pulled with no conflict at all to the latest dev branch.
I already post issues about the docs on that repo, and I’m of course volunteer. But I’m not sure I’ve suitable experience. English is not my mother tongue..
https://github.com/mx2DocsCommunity

It’s mainly to stop having to search for infos I half remember that I want to do it. So I think I’ll have a try anyway.
I’m open to any other way of working as long as it helps mx2.

@MarkSibly: It’s good to have your opinion about it. Thanks.

[Author]

Posts