Programming in Cobra

[gourD]

The 1.0 release is apprioaching and I wonder if Charles or someone else is working on Programming in Cobra book?

What kind of party will it be without such thing...

[Charles]

I can't say that I am working on a book. I prefer to put the docs in the wiki.

Writing a book typically implies:
* doing a lot of work that most people don't see until the book is released
* the book becomes out of date quickly after it is released

Of course, both issues could be addressed by writing the book online. Making it web accessible. Plus we could cross link pages. ... and now we're back to a wiki!

I realize some people would still prefer a book, but my time tends to be spent on the tech stuff. I notice in other communities this is often the case. For Python, Guido von Rossum hasn't written any of the Python books afaik. He's too busy working on Python.

[gourD]

I can't say that I am working on a book. I prefer to put the docs in the wiki.

There is lot of documentation in the wiki, but the usual problem I see with it is the lack of structure.

Writing a book typically implies:
* doing a lot of work that most people don't see until the book is released

I know - I did two ~500p books.

* the book becomes out of date quickly after it is released

Of course, both issues could be addressed by writing the book online. Making it web accessible. Plus we could cross link pages. ... and now we're back to a wiki!

Maybe wiki, but wiki with the structure, table of contents, some figures if required, index etc.

For instance, keeping wiki on Bitbucket (probably it's the same on Girthub), allows online editing, but keeping the wiki under e.g. Git so one can do writing offline as well which is indispensable for serious work.

Do not know - it was long ago when I was using it - if Trac has similar capability.

In any case, my suggestion is to transform present wiki into e.g. reST markup, keep it in the repo and then build e.g. Sphinx manual out of it and have it bundled with the official releases?

I realize some people would still prefer a book, but my time tends to be spent on the tech stuff. I notice in other communities this is often the case. For Python, Guido von Rossum hasn't written any of the Python books afaik. He's too busy working on Python.

Your time is precious, of course, but my suggestion is to make Cobra even more attractive and docs is always good for improving marketing.

What do you think and/or anyone enthusiastic to work on it

[hopscc]

but the usual problem I see with it is the lack of structure

There is a structure ( the current is the 2nd or 3rd) but I guess its not the structure you would like...
Its a wiki - have at it...
( start a link to a 'cobra book' and go from there... )

Maybe wiki, but wiki with the structure, table of contents, some figures if required, index etc.

Its not impossible to generate your desired structure, TOContents, figures, index etc into or alongside the existing wiki structure/pages:
all it would take is an alternate entry point off of or (instead of )cobra wiki.
The metacontent (TOC, figures, index) is additive ( where it doesnt already exist, root wiki page, site map), the existing pages can be referenced or split/copy+rewritten or new pages created to fit into 'the structure'.

[gourD]

There is a structure ( the current is the 2nd or 3rd) but I guess its not the structure you would like...
Its a wiki - have at it...

How many contributors are to the wiki?

I know that usually wiki is sold based on how easy is to contribute for everyone, but, imho, it's better to keep the content under version control, mostly contribute offline (although online is possible as well) and have one manual with easy navigation.

If you're satisfied with the current structure/outlook of the docs, then I won't complain any longer.

[hopscc]

Dunno - more than who have contributed code, less than who have written on the forum.
...
'better' in what way?

If you're satisfied with the current structure/outlook of the docs

My particular affliction is that I am never satisfied with anything...

Hell no, Complain all you like - Sometimes it indicates something we have all missed but unless I actually agree with your complaint ( and sometimes not even then) I'm not going to scratch your itch - thats up to you to do.

[gourD]

Dunno - more than who have contributed code, less than who have written on the forum.

I was just browsing forums and checking some interesting topic, not much, but I'm sure that besides lot of 'spam' accounts, there are several users who just joined and 'disappear' the same or few days after joining with just single/few post(s).

Using the web jargon we could say that Cobra or, at least, its forums, have bounce rate problem.

'better' in what way?

When I was still evaluating whether to use Cobra as programming language for my projects, I listed several languages and you've added few on the top:

Let me skip the big(ger) ones, iow. Haskell, Ada, D, Go, OCaml, Python(PyQt)for which there are plenty of doc/books/tutorials.

Now, let's check some of the remaining ones from your list:

Yeah theres lots of choices: Ada, Nimrod, PyQt_CPython, also Groovy, Boo, Gosu, Kotlin/Stab, Genie, Ceylon, Go, Obix, TypeScript

[*] Nimrod: there are 2 tutorials, user guide plus some extra docs like manual - nothing significant is kept in its wiki.
[*] Groovy is actually big documentation-wise, just see documentation link
[*] Boo also has structured docs with TOCs.
[*] Gosu has this with links for complete reference guide available as PDF for download
[*] Kotlin - nice structure
[*] Ceylon - nicely organized
[*] Obix - nicely structured tutorial and manual

So, based on the above, I'd say that the current Cobra's wiki/trac-based documentation is not on par with the language itself and inferior to many language's docs listed above. Of course, that's only in terms of structure/organization, but not content-wise.

Disclaimer: This is just humble opinion of new Cobra user desiring to see blossoming of the very fine language.

My particular affliction is that I am never satisfied with anything...

Well, if you're aware that it is shortcoming, then no harm.

Hell no, Complain all you like - Sometimes it indicates something we have all missed but unless I actually agree with your complaint ( and sometimes not even then) I'm not going to scratch your itch - thats up to you to do.

I do not want to disturb community too much as noob, but the point is that (maybe) I'm not scratching my own itch only.

[Charles]

I was just browsing forums and checking some interesting topic, not much, but I'm sure that besides ... there are several users who just joined and 'disappear' the same or few days after joining with just single/few post(s).

I don't follow you here. I have no idea why this would matter. Nor would I expect that you couldn't find mailing lists where people post a couple times and then move on. People who check out new languages come and go. Consider that you have apparently checked out at least 7, but I doubt you're on their irc channels and mailing lists every day for all 7.

Re: other lang docs, I'm suprised you listed http://boo.codehaus.org/Home as a counterexample, because I'm pretty sure that is their wiki! Also they said they were moving content to another wiki...

Ceylon's docs look clean but the left third of my window is consumed by whitespace and some nav links. Not ideal imo.

Re: Cobra's structure, my attempt to solve that was creating these pages:
LanguageTopics
LibraryTopics

Not to mention the outline on the main wiki page which has occasionally been re-organized.

But I have no problem at all if you want to start a new wiki page with a different outline and even new topics. That's the nice thing about wikis--you can do that. And we don't have to migrate the wiki for you to do this today. It takes seconds to get a wiki page started.

I do not want to disturb community too much as noob, but the point is that (maybe) I'm not scratching my own itch only.

I don't recall other complaints in this same vein in the past. Usually doc complaints have more to do with something missing. Maybe getting a complaint on structure or presentation is a good sign then.

[gourD]

I don't follow you here. I have no idea why this would matter. Nor would I expect that you couldn't find mailing lists where people post a couple times and then move on. People who check out new languages come and go. Consider that you have apparently checked out at least 7, but I doubt you're on their irc channels and mailing lists every day for all 7.

It's true that people come and go...However, if e.g. my web analytics software shows that I've high bounce rate it tells me it's better to do something about it despite my assumptions that everything is fine with my web pages.

So, I've feeling, based on short 'research' of forums, that it's happening here.

Here is one interesting article I just read which might illustrate the point.

Otoh, let me say that my checking of 'at least 7' languages didn't consist of few posts, but I mostly spent considerable time evaluating it. On my bookshelf there are few Haskell & Python books, I own D book, was submitting comments (as beta tester) to the upcoming OCaml book, spent time in Nimrod's IRC, posted a lot in Cython lists as well as spent time in #ada, posting to the list and even ordered Ada book which got lost on the way to Croatia which triggered the signal that maybe that's not THE language I'm looking for.

Re: other lang docs, I'm suprised you listed http://boo.codehaus.org/Home as a counterexample, because I'm pretty sure that is their wiki! Also they said they were moving content to another wiki...

That was my mistake - it's clearly the least good docs amognst all other candidates, but stiil their Primer & Language guides have clear TOC and, at least some navigational links to go through.

Ceylon's docs look clean but the left third of my window is consumed by whitespace and some nav links. Not ideal imo.

Online rendering is not the best indeed, but keep on mind few things:

[*] accrording to Wikipedia Ceylon is 5 yrs younger (appeared in 2011)
[*] release ships with Language spec document which is available as single page, multiple pages with navigational links and ~110p PDF (it's available online as well)
[*] language spec is very nicely semantically structured and generated from markdown source by DocBook stylesheets

Re: Cobra's structure, my attempt to solve that was creating these pages...not to mention the outline on the main wiki page which has occasionally been re-organized.

The problem which I see with wikis in general is that's it's very easy to create a page, but then one easily lose the structure.

Try to browse documentation for Tiki project for a short period of time and I hope you'll understand my point.

But I have no problem at all if you want to start a new wiki page with a different outline and even new topics. That's the nice thing about wikis--you can do that. And we don't have to migrate the wiki for you to do this today. It takes seconds to get a wiki page started.

Huh...my point is that wiki is not good as main documentation, but it can serve as providing supplementary info and I believe that to re-organize docs it would require to keep docs in the source repo, use some standard markup (I won't throw my favorites), create tutorial, user guide and manual and ship everything in release tarball.

I don't recall other complaints in this same vein in the past.

It's not that everybody barks aloud.

At the present moment, the organization of the docs in the wiki is very incompatible with the elegance of the language itself, so I wonder, seeing your taste as language designer, how can you tolerate it...it must be due to time constraints.

Usually doc complaints have more to do with something missing. Maybe getting a complaint on structure or presentation is a good sign then.

It's. Don't forget that I've become seriously interested for Cobra mostly based on what I've seen/read and not on what I have done with the language.

[hopscc]

My Q re 'better in what way' was wrt to your doc content process comment : this

it's better to keep the content under version control, mostly contribute offline (although online is possible as well) and have one manual with easy navigation.

rather than your comparison to the doc pieces of other languages you've looked at.

Why do you say a versioned and gated , offline, single (one-true) doc content with 'easy' ( presumably different) navigation is better than
a wiki ( readily, widely and freely accessible, always online, mutable, multi-form layout with inserted hyperlinking (for e.g.) ?