Closed RobertoMalatesta closed 7 years ago
ShtiliyanUzunov
commented
7 years ago There are tons of code examples at https://openui5.hana.ondemand.com/explored.html - you can see control usage examples, qUnit testing, OPA testing, we have tutorials for end to end app development.
qualiture
commented
7 years ago Actually, I found the ui.commons / ux3 docs quite horrible... it were just code snippets, not integrated examples using best practices, and (especially the sap.ui.tables) examples were never what I was looking for.
Also, since it were verbose Javascript examples instead of the more clean, hierarchical XML / HTML examples -- yes, I have a web development background, and yes, I like Javascript, but not when writing views :) -- I haven't used them at all.
Being used to Java-style API docs, I think the UI5 API docs are just fine. It could be improved in displaying for instance event object / map structure for certain parameters, but the inheritance etc is described just fine.
RobertoMalatesta
commented
7 years ago Hi @ShtiliyanUzunov @codeworrior (bringing here the other discussion as well),
There are tons of code examples at https://openui5.hana.ondemand.com/explored...
Yes, but those examples are XMLForms based, not programmatic (programmatic: where controls are not declared in XML but created by Javascript statements).
Can you give me a link to the ux3 documentation you are looking at ?
if you go four tabs after the explored one you will see the controls.
Click it and search i.e. for dialog
You will see the deprecated doc of commons.Dialog at page:
https://openui5.hana.ondemand.com/#test-resources/sap/ui/commons/demokit/Dialog.html
If you scroll down the page you will see, just like in the other old controls, running examples and code snippets:
API are linked as well. (badly, some work could have been done on that -- but that did the work). This level of documentation is non-existent on mobile components. It could have been improved, for sure, but having JS code snippets for almost everything was really handy.
What do you mean by test_resource examples ?
/test_resources is a directory of the UI5 distro that has some examples left in it.
It's the only existing source of documentation for using ui5 in a pure programmatic way.
--R
RobertoMalatesta
commented
7 years ago Hi @qualiture, I agree that that kind of documentation could have been better, but best is enemy of better and I don't believe that the new doc is nothing more of a set of ready-to-cut-and-paste-don't-care-how-they-work xml examples.
Also, since it were verbose Javascript examples instead of the more clean, hierarchical XML / HTML examples
We had the same discussion on #873. I don't want to change your mind, I'm only asking OpenUI5 not to convert the project to a one-trick-pony.
In short:
"You can keep your XML Views if you want it"
I'm just asking to
"Make OpenUI5 great again"
--R
RobertoMalatesta
commented
7 years ago .. from #1252: Hi @codeworrior
I'm a friend of the programmatic documentation (parents should try to be a friend to their children, shouldn't they?).
So I found the responsible for me choosing UI5 :laughing:
But don't you think that the Explored App can help developers to a similar extend?
Errr... well... No. It completely lacks any connection to the programmatic JS approach.
I understand that the easy editing + run in a single page is missing.
This is really handy if you want to test components or, like me, create a Typescript wrapper around them and use them in a real contract-based OOP system.
But on the other hand, the samples can be much more complex now and closer to a real world scenario
A big example instead of a specific set for each component is only messy if you want to focus on a single component usage; with no programmatic examples if I want to grasp a component logic I have to convert XML Views with some try and error (==time).
Besides, and a slightly OT:
(they can consist of multiple files likes views + controllers, components + manifest, Opa tests, mock data etc.).
Entropy is entropy by any other name. If for a start if you have to write three files for having a simple popup something is questionable in the approach.
A programmatic JSView can pack the whole logic of a complex app into a single file: thus a single get, being able to minify, reduce latency, component loading errors when mobile line is defective, etc.
Giving out JSViews has effects on:
And there is a rich set of those examples.
Nothing programmatic. They all look like cut and paste no-brainy templates, sorry.
Personally, I sometimes miss the explanatory texts - if they are not added as comments in the sample sources.
Given the amount and the tone of questions either on stackoverflow, here or on Scn you're not the only one (me in) :laughing:
AFAIK, the colleagues responsible for documentation did interviews with different user groups and as a result decided to focus on the Explored App and to abandon (deprecate) the old, single page programmatic documentation. This decision was surely taken under the impression, that the Explored App can give the same or even better benefit to developers.
Which users group were interviewed? It could have been a plus if this process involved the github users as well.
I assume that the colleagues are highly interested in feedback to the samples and to the Explored App in general. Maybe you (and others) want to add such feedback to #1254.
Great.
Kind Regards, Frank
Kind regards,
Roberto
Hi folks.
Main reason I adopted UI5 three years ago was thet ux3 modules had a good programmatic documentation.
Having code snippets to test and modify a single feature was a plus for getting bugs in the platform as well. Now it's more than 2 years that sap.m went out but the documentation is pretty horrible.
Since (on top of that) a lot of glitches can be caught by Javascript only, is there any remote chance to see documentation not only as test_resources examples but something more structured (i.e. with tests, snippets, API embedded into it as the old ux3 and commons ones) ?
This is vital for UI5 to survive.
Thank you in advance,
--R