Question about the documentation

[zeffii]

A couple of us from the Coursera IPMDA course are interested in doing a revamp of the current documentation. These would be unofficial docs, but they could prove to be a testing ground for nicer on-line documentation which is community driven.

My question is how OK are you and the team with the situation where we might be copying and elaborating on existing docs, the docs themselves will be open source and subject to the same license as ChucK.

I was thinking something along the lines of https://github.com/guillermooo/sublime-undocs which looks like this : https://sublime-text-unofficial-documentation.readthedocs.org/en/latest/ . A distributed approach like a dedicated github repo for the docs would (i think) encourage people to contribute more freely and the issue tracker could form a small community dedicated to user-documenting this brilliant thing called ChucK.

[nathanleiby]

I'm not on the chuck team, but I think this is a great idea!

On Sat, Dec 21, 2013 at 15:36, Dealga McArdle notifications@github.com="mailto:notifications@github.com"> wrote:

A couple of us from the Coursera IPMDA course are interested in doing a revamp of the current documentation. These would be unofficial docs, but they could prove to be a testing ground for nicer on-line documentation which is community driven.

My question is how OK are you and the team with the situation where we might be copying and elaborating on existing docs, the docs themselves will be open source and subject to the same license as ChucK.

I was thinking something along the lines of https://github.com/guillermooo/sublime-undocs which looks like this : https://sublime-text-unofficial-documentation.readthedocs.org/en/latest/ . A distributed approach like a dedicated github repo for the docs would (i think) encourage people to contribute more freely and the issue tracker could form a small community dedicated to user-documenting this brilliant thing called ChucK.

— Reply to this email directly or view it on GitHub.

[heuermh]

Hello Dealga,

There is already a set of community-driven ChucK docs at

http://www.flossmanuals.net/chuck/

The fact that you weren't already aware of it is a failure of sorts. The FLOSS Manuals site has a nice process for documentation collaboration and publication, although maybe not as low a barrier to entry as something published from GitHub.

michael

On Sat, Dec 21, 2013 at 2:36 PM, Dealga McArdle notifications@github.comwrote:

A couple of us from the Coursera IPMDA course are interested in doing a revamp of the current documentation. These would be unofficial docs, but they could prove to be a testing ground for nicer on-line documentation which is community driven.

My question is how OK are you and the team with the situation where we might be copying and elaborating on existing docs, the docs themselves will be open source and subject to the same license as ChucK.

I was thinking something along the lines of https://github.com/guillermooo/sublime-undocs which looks like this : https://sublime-text-unofficial-documentation.readthedocs.org/en/latest/. A distributed approach like a dedicated github repo for the docs would (i think) encourage people to contribute more freely and the issue tracker could form a small community dedicated to user-documenting this brilliant thing called ChucK.

— Reply to this email directly or view it on GitHubhttps://github.com/spencersalazar/chuck/issues/27 .

[zeffii]

Thanks for this reply, and for LiCK!, I was aware of that effort - and found useful information in those docs too concerning the Event References (which is weak on the princeton/stanford sites).

[heuermh]

ok, why then the suggestion to start something new? It is hard enough keeping docu up-to-date in one place.

Just curious,

michael

On Sun, Dec 22, 2013 at 3:09 PM, Dealga McArdle notifications@github.comwrote:

Thanks for this reply, I was aware of that effort.

On Sun, Dec 22, 2013 at 9:27 PM, Michael L Heuer notifications@github.comwrote:

Hello Dealga,

There is already a set of community-driven ChucK docs at

http://www.flossmanuals.net/chuck/

The fact that you weren't already aware of it is a failure of sorts. The FLOSS Manuals site has a nice process for documentation collaboration and publication, although maybe not as low a barrier to entry as something published from GitHub.

michael

On Sat, Dec 21, 2013 at 2:36 PM, Dealga McArdle < notifications@github.com>wrote:

A couple of us from the Coursera IPMDA course are interested in doing a revamp of the current documentation. These would be unofficial docs, but they could prove to be a testing ground for nicer on-line documentation which is community driven.

My question is how OK are you and the team with the situation where we might be copying and elaborating on existing docs, the docs themselves will be open source and subject to the same license as ChucK.

I was thinking something along the lines of https://github.com/guillermooo/sublime-undocs which looks like this :

https://sublime-text-unofficial-documentation.readthedocs.org/en/latest/. A distributed approach like a dedicated github repo for the docs would (i think) encourage people to contribute more freely and the issue tracker could form a small community dedicated to user-documenting this brilliant thing called ChucK.

— Reply to this email directly or view it on GitHub< https://github.com/spencersalazar/chuck/issues/27> .

— Reply to this email directly or view it on GitHub< https://github.com/spencersalazar/chuck/issues/27#issuecomment-31095119> .

— Reply to this email directly or view it on GitHubhttps://github.com/spencersalazar/chuck/issues/27#issuecomment-31096021 .

[zeffii]

Michael, Several reasons, some admittedly superficial, others related to convenience and extendibility.

Superficial because I think both sources don't look very appealing, they look pre "web 2.0". This doesn't reflect their content quality, but for some reason how something looks matters to a lot of people. I also like designing pretty stuff, and would like to add some d3.js graphs to show the behaviour of parameter changes. and syntax highlighted code.

Further, I like the convenience of github -- it's integrated into my workflow, I also want to be able to break any convention that gets in the way of achieving the goal here.

I don't think it's difficult to keep docs up to date, perhaps this has more to do with the amount of people who actively check them. I don't know much about the FOSS manuals system, but I do know that if it was hosted on github that it's very convenient to see (for everyone! not just those logged in) when the last edits were made and by who and what they were.

[heuermh]

Cool, go for it!

A lot of work went into the FOSS Manual docu so it would be a shame if that went to waste. I don't remember the format or process exactly but I think it was MediaWiki-ish.

I have been ChucK'ing for a while (10 years now?) so it is nice to see things like the Coursera course bringing new people in.

michael

On Mon, Dec 23, 2013 at 2:32 PM, Dealga McArdle notifications@github.comwrote:

Michael, Several reasons, some admittedly superficial, others related to convenience and extendibility.

Superficial because I think both sources don't look very appealing, they look pre "web 2.0". This doesn't reflect their content quality, but for some reason how something looks matters to a lot of people. I also like designing pretty stuff, and would like to add some d3.js graphs to show the behaviour of parameter changes. and syntax highlighted code.

Further, I like the convenience of github -- it's integrated into my workflow, I also want to be able to break any convention that gets in the way of achieving the goal here.

I don't think it's difficult to keep docs up to date, perhaps this has more to do with the amount of people who actively check them. I don't know much about the FOSS manuals system, but I do know that if it was hosted on github that it's very convenient to see (for everyone! not just those logged in) when the lasts edits were made and by who and what they were.

— Reply to this email directly or view it on GitHubhttps://github.com/spencersalazar/chuck/issues/27#issuecomment-31142170 .

[spencersalazar]

Hi all,

I am the first to admit that the documentation is sorely in need of attention. For myself as a ChucK user, the most reliable documentation tends to be the source itself, which is not a great situation. I am happy to see community interest in improving the documentation, and would be interested in linking/featuring such efforts on the official ChucK website when they are in a reasonable state of maturity and accuracy.

You may also want to gauge general community interest on the ChucK users email list (https://lists.cs.princeton.edu/mailman/listinfo/chuck-users), as this github repo is my "unofficial" git mirror of ChucK, which actually lives in SVN. chuck-users is to my knowledge the most active ChucK community forum.

Rock on!

spencer

[arnauorriols]

Let me retake this discussion so lately, I read the emails but didn't got the time to write until now. I came to know about the ChucK community thanks to the Coursera MOOC as well. In my humble opinion, ChucK documentation, and specially this of flossmanuals, are actually very good, specially as a manual/tutorial. What I think many of us experienced in this course is that what is actually lacking is the code reference, a quick and exact reference of every method of every class, the range of the arguments, the inheritance trees... A sort of javadoc for ChucK. It's not that it's missing, of course, but sometimes it's not accurate enough, and could have some improvement.

I would definitely like to help on this matter too!

Arnau.