Forums

Discoverable documentation

General discussion about Cobra. Releases and general news will also be posted here.
Feel free to ask questions or just say "Hello".

Discoverable documentation

Postby kobi7 » Fri Jan 03, 2014 12:05 am

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
Falun Dafa is Good.
Truth, Compassion, Forbearance is Good.
kobi7
 
Posts: 82
Location: Israel

Re: Discoverable documentation

Postby kirai84 » Fri Jan 03, 2014 1:34 am

+1, good idea.
kirai84
 
Posts: 24

Re: Discoverable documentation

Postby hopscc » Fri Jan 03, 2014 4:26 am

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...)
hopscc
 
Posts: 632
Location: New Plymouth, Taranaki, New Zealand

Re: Discoverable documentation

Postby nerdzero » Fri Jan 03, 2014 5:10 pm

kobi7 wrote: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 :D
nerdzero
 
Posts: 286
Location: Chicago, IL

Re: Discoverable documentation

Postby kobi7 » Sat Jan 04, 2014 11:44 pm

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. :-)
Falun Dafa is Good.
Truth, Compassion, Forbearance is Good.
kobi7
 
Posts: 82
Location: Israel

Re: Discoverable documentation

Postby Charles » Sun Jan 05, 2014 12:15 pm

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.
Charles
 
Posts: 2515
Location: Los Angeles, CA

Re: Discoverable documentation

Postby kobi7 » Mon Jan 06, 2014 4:30 am

Yeah I think you're definitely right about that.
Falun Dafa is Good.
Truth, Compassion, Forbearance is Good.
kobi7
 
Posts: 82
Location: Israel

Re: Discoverable documentation

Postby hopscc » Tue Jan 07, 2014 2:30 am

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


almost sounds like a worked tutorial, eh?
hopscc
 
Posts: 632
Location: New Plymouth, Taranaki, New Zealand

Re: Discoverable documentation

Postby Charles » Tue Jan 07, 2014 1:22 pm

hopscc wrote:
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.
Charles
 
Posts: 2515
Location: Los Angeles, CA

Re: Discoverable documentation

Postby hopscc » Wed Jan 08, 2014 5:20 am

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...
hopscc
 
Posts: 632
Location: New Plymouth, Taranaki, New Zealand

Next

Return to Discussion

Who is online

Users browsing this forum: No registered users and 43 guests