Add doc for Stateful

[wkeese]

Updated from original delite/Stateful reference doc.

BTW we also need doc for Observable.

[cjolif]

You should add the YAML headers similar to delite/deliteful.

[asudoh]

LGTM. One thought I have is moving “implementation notes” section to another .md file so that regular users can focus on the API. But if nobody else has comments/changes in short term we probably should squash the changes and push.

[cjolif]

@asudoh I agree this is user documentation not design documentation. So implementation notes should probably be put aside.

[wkeese]

Grr, we discussed this a year ago and agreed to put implementation notes here. That's why many of the delite reference guide files have implementation details. Are you guys saying to double the number of files? It sounds like overkill.

[cjolif]

@wkeese a year ago we were just starting this project and we needed to gather implementation details so we can review/discuss it, using docs directory sounded like the simplest approach. And we were not worrying about users yet. Now we have made progress and we need to share with users how to use delite(ful) and I do think this will confuse them to have documentation mixing the how to use and the design decision which are of interest to some of them but not necessarily all of them. Also I'm not sure this means doubling the number of files (for example do we really need one documentation file about implementation notes for each of the classes? maybe not? maybe a single design document would be enough?). Whatever we do several implementation notes files, or a single one I think something must be done to better draw the line between user guide and implementation notes.

cc: @pruzand @ccmitchellusa for feedback

[wkeese]

Users will be confused even though there's a giant header for that section that says "Implementation notes"?

[cjolif]

ok maybe they won't be confused thanks to the header, but I still think it is very unusual to see that kind of things in user documentation and they might wonder why they see that here and what it implies. In other words this might raise more questions than it solves issues. That said this is not dramatic but I still think it is worth doing something more separated between user documentation and more of design document.

[asudoh]

Let me share another perspective on “implementation notes” topic. What I’d expect from regular .md files in docs directory is something akin to http://www.polymer-project.org/docs/polymer/polymer.html, http://knockoutjs.com/documentation/introduction.html or https://docs.angularjs.org/tutorial. I recall older docs.angularjs.org site used to have many articles about its internal design, but I can no longer find one. Polymer TemplateBinding has a document of some internals (http://www.polymer-project.org/docs/polymer/databinding-advanced.html). As far as I recall those “internal” documents in Angular and Polymer are in separate documents from ones for how to use them.

I think reducing learning curve would be one of our priorities and having new developers free from our internals would be important, if it makes sense to everybody.

[wkeese]

I see where you guys are coming from. I guess my issue is that we need to be explaining delite's advantages. Otherwise everyone will just go to Polymer. About half of "Implementation notes" for Stateful are doing that. I don't want to hide that information on a page no one will read.

[cjolif]

. I guess my issue is that we need to be explaining delite's advantages.

I fully agree with that. But I'm not sure a "implementation notes" section in user doc of a class is really helping. A global .md explaining the design, the rationales, the advantages of that design would probably be more helpful.

[asudoh]

A global .md explaining the design, the rationales, the advantages of that design would probably be more helpful.

Agreed, it may be an overview document of delite, or a dedicated document for “why delite?". It also means that we should explain that in an easy-to-understand manner. Same thing applies to liaison.

[wkeese]

Fixed in f0c84c2.