Discoverable documentation

[kobi7]

Regarding documentation, and discoverability
I would warmly suggest having a wiki page, showcasing all of cobra in one page "AllOfCobraInOnePage"
in other words, code samples for every sort of syntax, special handlings and idiomatic ways.
that syntax will be linked to the corresponding documentation for that feature.
a reason for the rationale is that sometimes it's hard to search for "?=" in the website.

in implementation terms, I'm just talking about writing code: interfaces, classes, contracts, mixins, usings, events, exceptions, etc.
down to definitions declarations and code, and showing all the special cases that are supported.
for example * for stream, and a,b = b,a for swapping (multiple assignment)

I think there are numerous test cases in the Cobra source code.
I am talking about making an outline, general overview of the entire cobra feature set, by having it all in one "compressed" page.

What do you think? Would that be valuable to you? To me, I'm sure it will be.

Thanks, Kobi

[kirai84]

+1, good idea.

[hopscc]

Yeah - put entries for all the doc on one page - code samples for every sort of syntax, special handlings and idiomatic ways,
link to "the corresponding documentation for that feature"

That should work really well

Do feel free - its a wiki, add as you like- all it has to be is an improvement.

put a link in here to an 'allOfDocPage' , create it and and start filling it in

Start here Language Topics
It'll point you to all the bits you'll want to put on your page...

....

You might save yourself some time by looking through the pages in the trac index - theres probably still something in there similar to what you want (but old and time rotted /unfinished)- that could be a starting point
If its still there you'll probably find its unintelligibly large, disorganised and impenetrable (at start point ) and doesnt improve much no matter what you add to it or how you augment it from that, and then you'll reorg it to something more like this.

I can say this cos thats something like has already been done.....

But have a go - your effort may well be more successful than previously


(The forum already has discussions about better doc/update/structure lines - thay seem to indicate that a major lack is a well structured tutorial/teaching sequence which I presume is what you are heading towards with your posting.... Its a little more than what you suggest though. Noone doing the doc has made any attempt/shown any interest at that yet...)

[nerdzero]

What do you think? Would that be valuable to you? To me, I'm sure it will be.

Similar posts have come up in the past too so you're not the only one looking for a different structure or easier way to find relevant documentation. I say go for it. Create "AllOfCobraInOnePage". It would make for a great test file too

[kobi7]

Okay, I was thinking maybe create examples that are less contrived.
for example, an AudioPlayer
I'm not sure I'm the best code designer, but I can give it a try, then you guys improve if you wish to help.
it will showcase at least the basic structure, and the csharp programmer would feel at home.
then we introduce the conveniences, and he will be lured
After that the new integrated features, and he will ponder what are they good for, and be intrigued.
then testing and contracts, getting used to python-style indentation, and wow nice language.
okay, okay, let's scratch our own itch with documentation first. There is always less time than what you had in mind.

[Charles]

For the "all in one" page, the examples should definitely be contrived because for any sample application such as:
- audio player
- chess game
- animated video game
- enterprise CRM app
- wiki web app

...you will have to be concerned with the app's functionality over hitting full coverage of Cobra language features. And someone learning Cobra may not find your particular app domain interesting which means they will find it distracting. For example, they may not want to learn about CRM concerns just to learn Cobra programming.

Not that there wouldn't be anything wrong with creating one of the above apps and then dissecting it. But I think you're conflating two good approaches that should be kept separate.

[kobi7]

Yeah I think you're definitely right about that.

[hopscc]

For the "all in one" page, the examples should definitely be contrived because ...

almost sounds like a worked tutorial, eh?

[Charles]

For the "all in one" page, the examples should definitely be contrived because ...

almost sounds like a worked tutorial, eh?

What's a "worked tutorial"?

This was the page that I recalled while reading this thread:
http://www.harding.edu/fmccown/vbnet_cs ... rison.html

You can see it goes through major language areas and libraries. Also, the examples are contrived so they can be short and "neutral" (not requiring knowledge of a specific domain).

I don't care if our page has another language for comparison on it or not, but the other aspects of this page make sense to me.

[hopscc]

Whats a "worked tutorial"

An expanded example of a contrived app ( code, description, and discussion) selected to show off the tutorial goal rather than
a working app...