search

project-iris / iris

Decentralized cloud messaging
iris.karalabe.com
Other
570 stars 32 forks source link

Documentation and code examples are missing #20

Open thedrow opened 10 years ago

thedrow commented 10 years ago

The README file should at least contain a quickstart section and the documentation (the book of iris) should be completed.

What exactly needs to be done in order to proceed?

Missing sections of the book:

karalabe commented 10 years ago

Just finished and uploaded the Run, Forrest, Run chapter.

BinaryBlob commented 10 years ago

I could work on some examples (I still have dozens of experiments). I think having a working example directory would be nice to have or do you want to have all the examples in the book @karalabe ?

karalabe commented 10 years ago

I was also considering adding an example/sample collection, though I haven't yet decided on exactly how/where to add it. I only intended to add a very small demo collection into the book of Iris, just enough to showcase its functionality, but nothing too advanced (these would be the nuts and bolts chapter). Whether I'll get to write the more advanced chapters (specifically regionrank/embree), and/or in how much detail, I do not know yet.

Still, it would be definitely valuable to have a working collection of examples, so I'm open to creating them. The question is where to put them? The book of Iris - as stated above - is not the best place, and I'd also refrain from putting them into the existing repos (core is not the place, and I don't like the idea of putting them into the binding repos as it would become a lot of additional effort to keep the many binding examples in sync (i.e. implement in all of them, or some might look incomplete)).

I think at this point the best way would be to have a separate samples, benchmarks, demos, whatnot repository that could have a lot less restricted structure and inherently not look weird if certain code snippets are available in only one language or another.

But I'm open to suggestions, so if you have a different view, do share :)

BinaryBlob commented 10 years ago

I agree with a seperate repository. Having everything in one place is nice if an example is not written in your language of choice, but is in another language that you can read.

ZeroMQ solves it in the same way, it has a big example repository (https://github.com/imatix/zguide/tree/master/examples).

karalabe commented 10 years ago

I'm fairly satisfied with that approach :) Although Iris would probably require a little reogranization example wise as the "guide"/"book" will (at least for now) be relatively shorter, and I also see having more detailed "use-case" examples available in only one language or another.

I'll ponder a bit about a possible structure and post an update if I come up with anything workable :)

thedrow commented 10 years ago

I'm really glad that this project is still being maintained but there's no progress on the documentation at all. pinging @karalabe just to make sure he remembers :)

karalabe commented 10 years ago

Well, I wouldn't call it at all, just not what you were looking for :) I've written a case study (paper | slides), I've publicly released the relay protocol specs and I've wrote/finished a 130+ page dissertation :P

But I'll try and pull in some of the stuff from my dissertation into the book of Iris. Only that they focus a slightly different things, so reworks are needed :) But I haven't forgotten about this.

BinaryBlob commented 10 years ago

I could write some documentation. My time is limited though, so what documentation has the highest priority to be written?

On Fri, Oct 24, 2014 at 9:16 AM, Péter Szilágyi notifications@github.com wrote:

Well, I wouldn't call it at all, just not what you were looking for :) I've written a case study (paper http://iris.karalabe.com/papers/2014%20-%20Juhasz%20-%20Decentralizing%20a%20CPS%20workflow%20system%20with%20cloud%20messaging%20(SYSY14).pdf | slides http://iris.karalabe.com/talks/confs/sisy_14.slide), I've publicly released the relay protocol specs http://iris.karalabe.com/specs/relay-protocol-v1.0-draft2.pdf and I've wrote/finished a 130+ page dissertation :P

But I'll try and pull in some of the stuff from my dissertation into the book of Iris. Only that they focus a slightly different things, so reworks are needed :) But I haven't forgotten about this.

— Reply to this email directly or view it on GitHub https://github.com/project-iris/iris/issues/20#issuecomment-60352468.

thedrow commented 10 years ago

@BinaryBlob The communication patterns are the most important unwritten documentation. The rest can wait.