Programming in Cobra

[nerdzero]

Content aside, I will say that I wish the search function in the wiki returned more relevant results. I always have a hard time finding the "for expression" syntax. Maybe a different structure would help that, maybe not.

In any case, I've found that the index page and Ctrl+F is pretty useful: http://cobra-language.com/trac/cobra/wiki/TitleIndex

[gourD]

...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.) ?

Well, I believe that the the quality of the 'doc pieces of other languages' speaks for itself.

Moreover, as I wrote earlier, it's possible to have versioned wiki which is also online (e.g. bitbucket, not sure about github), so one does not exclude the other.

Otoh, considering there are not so many contributors to the wiki and most of them are seriously involved with the project, I believe that even keeping the doc just under repo (of course, assuming DVCS), won't be a barrier to contribute.

Another feature would be that before every release the doc would be frozen like a code and generated for inclusion in the tarball, while 'development' version can be always available online. Check e.g. Sphinx which has latest stable and dev version available.

[hopscc]

I believe that the the quality of the 'doc pieces of other languages' speaks for itself

OK - so what makes you believe all those high quality doc pieces were generated using exactly and only the process you describe and that was the sole reason they are 'high quality' ( as opposed to 1 person or a small group generating them with or more likely without any external assistance or as 'closed' source).
I'd think a better indicator of quality output was a someone who knows what good targetted doc should look like, good architecture pointed at what you are trying to achieve, willingness to enforce/follow it, good book/tutorial writing skills and lots of user testing or input and iteration on the result, ...

Anyway

.... won't be a barrier to contribute

Of course it will - any additional overhead action is a barrier:
Just using a VCS - thats extra steps - both the idea of using, and getting the 'chosen' one, working out how to use it (over and above actually generating the content ) - complaining cos its not my favored one, and the syncing process itself...

That would filter out anyone who saw a mistake or thought of an addition/correction and just thought 'I can fix that'. Leading onto - hey this is easy write some more doc....
( I'm not sure I agree with either of your precondition assertions either)

Its not that your process wouldnt work to gen something but its a different dynamic than allowing anyone who just wants to fix/do some doc to do so ( more toward a committed-to-completion, semi-closed, doc-development group,...)

[hopscc]

Content aside, .... Maybe a different structure would help that, maybe not... index page

I too have problems trying to remember syntax for some of the expression forms:
Usually I can vaguely remember where it is in the doc structure but the index search is a good idea

With the current layout theres 2 problems wrt your specific example
- expressions doc need a full index to the expressions pages (same as Statements) containing all the expressions ( or all those docced )
theres a start but since not all the expressions are docced ( especially some of the less common ones/more useful ones) theres a hole.

The existing structure probably should have an additional index/TOC for just the language pages - or one for language and one for library
( rather than the entire wiki)


Generally re the doc, gourD makes some good points for quality doc in comparison to some other languages.
The doc content we have is pretty good developer doc (both by and for).

To my mind whats missing currently is good lumps for
- Why Cobra (should link fm wiki to the Documentation pages or otherwise tie that and features together somehow - the cobra 'teaser')
- 'Getting Started' /'Intro to cobra'/Primer
- some of this exist in pieces (chucks original doc ) but its outside the wiki structure and not really in an intro form
- Tutorial ( copy pythons layout or something)

- I think a 'Programming in Cobra' book while an attractive idea is pointless for online doc unless it already exists as a e/dead-forest' book
downloadable ebook - yeah
the online info needs to be less conversational, more concise and in smaller digestible chunks.

( though dont let my opinion stop anyone from starting/writing same (online or not) - except Chuck - Chuck has to keep away from spending time on large amounts of doc and keep the cobra compiler development rolling along

[hopscc]

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

Forgot, was going to ask you about this:
What structure/organization do you think would be better ?

[gourD]

OK - so what makes you believe all those high quality doc pieces were generated using exactly and only the process you describe and that was the sole reason they are 'high quality' ( as opposed to 1 person or a small group generating them with or more likely without any external assistance or as 'closed' source).

Check those docs and to find out how they are generated and/or source code repos which may reveal how the doc is generated.

It does not matter whether it is group or 1 person (e.g. Nimrod is basically one-man-band), but the point is that most of the docs for the projects which I listed do not keep their main doc in wiki only.

I'd think a better indicator of quality output was a someone who knows what good targetted doc should look like, good architecture pointed at what you are trying to achieve, willingness to enforce/follow it, good book/tutorial writing skills and lots of user testing or input and iteration on the result, ...

I never wrote that for Cobra's docs there is problem with the content, but with the structure

Of course it will - any additional overhead action is a barrier:
Just using a VCS - thats extra steps - both the idea of using, and getting the 'chosen' one, working out how to use it (over and above actually generating the content ) - complaining cos its not my favored one, and the syncing process itself...

That would filter out anyone who saw a mistake or thought of an addition/correction and just thought 'I can fix that'. Leading onto - hey this is easy write some more doc....

First of all, do some research and find out:

[*] how many people contributed significant amount of docs in last year?

[*] how many of those are not techy-savvy enough to contribute doc 'patches' using some (D)VCS ?

My opinion that any serious contributor to the project, should be familiar with the tools/VCS used by it.

I also complain that wiki is not my beloved tool, so what?

You can't satisfy everybody, but decide what is good for the project itself.

( I'm not sure I agree with either of your precondition assertions either)

No problem.

Its not that your process wouldnt work to gen something but its a different dynamic than allowing anyone who just wants to fix/do some doc to do so ( more toward a committed-to-completion, semi-closed, doc-development group,...)

If keeping wiki and having badly organized docs for the sake of occacional contributors being able to fix some typos online, then I consider it's a bad trade off.

I just expressed my opinion trying to offer constructive criticism in order to improve the image of the whol project 'cause atm I can't improve compiler itself, but I'm respecting your opinion in regard and understand that it is allowed to differ from mine.

Now, I won't beat that dead horse any longer considering that enough is said in regard.

[hopscc]

I never wrote that for Cobra's docs there is problem with the content, but with the structure

OK - So what would be a preferable/better structure?

[Charles]

I never wrote that for Cobra's docs there is problem with the content, but with the structure

OK - So what would be a preferable/better structure?

And this gets to my earlier suggestion to create a wiki page with the structure that you want to see. @gourD, you balked at that, pointing out that you thought the wiki was a poor medium for the docs (I'm paraphrasing). But my counterpoint is that whatever structure you think would make sense for the Table of Contents of a Cobra Manual PDF, could be put in a wiki page. If you can type it into a text editor, you can type it into a wiki page for us to look at.

I do agree that it would be nice to snapshot the docs and include them with the installation. That's pretty low on my list though. My biggest interest right now is supporting the IDE efforts through testing and tweaking the Cobra compiler+parser+lexer for reuse.

[gourD]

@gourD, you balked at that, pointing out that you thought the wiki was a poor medium for the docs (I'm paraphrasing).

Correct.

But my counterpoint is that whatever structure you think would make sense for the Table of Contents of a Cobra Manual PDF, could be put in a wiki page. If you can type it into a text editor, you can type it into a wiki page for us to look at.

That's half-baked solution 'cause the medium is, imho, not right and encourages poor workflow.

After some time, we'd arrive at the same spot.

For instance, if the project moves from CVS/SVN to DVCS, then it does not make sense to keep the same old pattern where everyone just work with the 'central' repo.

I do agree that it would be nice to snapshot the docs and include them with the installation.

Good...something, at least.

That's pretty low on my list though. My biggest interest right now is supporting the IDE efforts through testing and tweaking the Cobra compiler+parser+lexer for reuse.

I've never meant that you should do it, but I'm suggesting change in the present workflow, similar to suggestion to move to DVCS, possibly git, in order to keep docs in the code repo.

Otoh, I'm very well aware that such things are sensitive requiring adjustments to our mental models how we're habituated to do things and, possibly, even going out of our comfort zones (which we all have). for no apparent benefit to justify it.

So, I'll stop here until the time matures when we can arrive at some sort of consensus and focus on doing other things I can be (more) productive.

[Charles]

That's half-baked solution 'cause the medium is, imho, not right and encourages poor workflow.

I already understand that's your perspective. But that doesn't change my suggestion because if I ask you "gourD, what hierarchical structure do you want to see in the PDF book?" then you have to type this somewhere:

Part I: Foo
Chp 1: Bar
Section 1: Baz
Section 2: ...
Chp 2: ...
etc.

And whether you do that type that in the forums, email or the wiki is largely irrelevant in the short run. Unless you're so allergic to the trac wiki you won't ever use it all. I realize using it might require an adjustment to your mental model.