フォーラム

ホーム » Liferay Portal » English » A. Liferay's Community

構造的に表示 平面上に表示 ツリー上に表示
スレッド [ 前へ | 次へ ]
toggle
James Falkner
Poll Results: Community in 2011
2011/02/03 11:01
答え

James Falkner

LIFERAY STAFF

ランク: Liferay Legend

投稿: 1325

参加年月日: 2010/09/17

最近の投稿

Community poll results are in! The question was:

Which part of Liferay's community needs the most attention in 2011?

The results are (see attached pie chart for fun):
  1. 33% Developer Documentation
  2. 16% Marketplace (App Store for Liferay)
  3. 16% Roadmap clarity/participation
  4. 14% Ticket Maintenance/Resolution
  5. 5% More Liferay LIVE sessions or other screencasts
  6. 5% Social/Website features (e.g. social equity, private msgs)
  7. 5% Community Development and Leadership
  8. 3% Wiki Maintenance
  9. 3% Wider selection of plugins
  10. 0% More User Groups
  11. 0% Forum/IRC participation
  12. 0% More Community Events

With "Developer Documention" being the clear winner, what kinds of developer documentation do you want to see? For example, better Javadocs, entity documentation, REST API documentation, more examples (with documentation, etc), or what?

Marketplace, Roadmap, and Ticket Maintenance were virtually tied for second, and we're working on all of the above. For Marketplace and Roadmap, in particular, expect to see better community engagement on these this month. As for Ticket Maintenance, I am coordinating a couple of programs (100 PaperCuts, and the Leadership program) to hopefully help in this area. More ideas are welcome!
画像の固定

添付ファイル: Screen shot 2011-02-03 at 1.24.42 PM.png (73.6k)
Joel Peterson
RE: Poll Results: Community in 2011
2011/02/03 16:58
答え

Joel Peterson

ランク: New Member

投稿: 22

参加年月日: 2010/02/18

最近の投稿

I would like to see Javadocs for the classes available to the SDK that have comments for each method including any assumptions the method may make about parameters.

I would also like to see more examples of taglib use from the SDK.
chris anderson
RE: Poll Results: Community in 2011
2011/02/03 17:29
答え

chris anderson

ランク: New Member

投稿: 9

参加年月日: 2010/04/09

最近の投稿

(1)
Examples, examples, examples -- official examples that I don't need to read through forum posts to verify are correct. Preferably a repository of easily searchable examples somewhere - no blogs.

(2)
UML diagrams of framework inner-workings, and services created by servicebuilder (please don't say it's not necessary because it's all "automatic").

(3)
Javadocs -- I'm sure Liferay is already aware that the Javadocs aren't really documentation, they are just easier-to-read function signatures with no actual contextual information or information about side-effects, what-ifs, assumptions, etc. As such, it would be a misnomer to say the LR framework is "documented" in this way. We would like some descriptions of what the functions do specifically. We have spent many hours debugging, and putting printlns into ext code to figure out why a call to one of the localservice classes wasn't working - only to find out it was because of something simple that could have easily been noted in a doc.

A couple of examples:

Birthdates (and I presume other dates) are validated using a function buried deep in the framework called isJulianDate(), which so happens to assume that your month is zero-based -- what happens if you don't format the date right? "Exception: null" It took several hours to debug this as part of a parameter list for userlocalservice.updateUser(), something that would have been figured out in five minutes with proper docs.

Speaking of userlocalservice.updateUser() -- this function has a bazillion parameters if you want to make use of it (but that's a different topic). It's nearly impossible to use this function properly without throwing an exception -- it would be nice to know what it's actually doing without reading the pages long code that takes forever to find the right file (wait was it userimplservicelocal, or localserviceuserimpllocal? - wish I had a doc explaining which is which!). For instance, what happens if I pass null for my organization array? Nothing? My orgs are cleared out? In this case we learned by trial-and-error that it has no change, yet, mysteriously, this same behavior does not hold for other parameters.

I could go on...but...

In general, it's my belief that it should not require a poll to come to the conclusion that an enterprise level API should have enterprise level documentation, especially when you're paying for an enterprise license.

</vent>
James Falkner
RE: Poll Results: Community in 2011
2011/02/04 8:43
答え

James Falkner

LIFERAY STAFF

ランク: Liferay Legend

投稿: 1325

参加年月日: 2010/09/17

最近の投稿

Chris, I understand your frustration - I too have faced the same issues and ended up adding SOP statements in various places or stepping through in a debugger to find out how to properly use various APIs. Polls and such continually reinforce the fact that we need better documentation, and we are working on it, especially as we get closer to having a real Marketplace through which our larger community can buy and sell apps. We need to improve our documentation (esp. in terms of reference documentation that you suggest) if we are to get people seriously investing in building out the ecosystem of aftermarket apps and things like that. We are working on it as quickly as possible, and you should see some new reference docs out in the next couple of months.

I feel we have enough 'getting started' and administration docs, with lots of supporting text, and now we need to back that up with core reference docs so developers don't have to wait through hundreds of pages to find the documentation for that one particular API or concept they are concentrating on.
Tobias Käfer
RE: Poll Results: Community in 2011
2011/02/04 9:57
答え

Tobias Käfer

ランク: Regular Member

投稿: 128

参加年月日: 2008/03/28

最近の投稿

One thing I am missing since 2005 (we started with Liferay then) is a dcoumentation of how all those litte tiny and not so tiny classes of Liferay fit together.
You are able to find some kind of documentation for some parts in the wiki or in the forums. But it takes some time. And if you don't find anything (maybe one used the wrong search term) you mostly end up with a look in the sources.
But that might get more confusing than anything else. We had quite a few interns, that got lost between all those interface, abstract classes and implementations. It always takes time to find your way through those classes that are available from portal-services and from portal-impl and how you put them together. And as a consequence where you have to implement your functionality (hook, portlet, ext etc.).
Denis Signoretto
RE: Poll Results: Community in 2011
2011/02/05 0:52
答え

Denis Signoretto

ランク: Regular Member

投稿: 220

参加年月日: 2009/04/21

最近の投稿

IMHO At the moment,

there is a lack of "official" documentation (Getting Started, examples, advance use case) about Web Content Management.

D.
Jorge Ferrer
RE: Poll Results: Community in 2011
2011/02/05 7:06
答え

Jorge Ferrer

LIFERAY STAFF

ランク: Liferay Legend

投稿: 2764

参加年月日: 2006/08/31

最近の投稿

Hey guys,

Thanks everyone for your suggestions.

I wanted to let you know about some of the ongoing initiatives to improve the available official documentation:
  1. A new edition of the "Developer's Guide" will be available in a few days. It will contain several new chapters that people have been demanding and links to the available reference documentation (which will be growing quickly).
  2. Rich is writing the last chapter of "Liferay in Action" so the book will be available soon.
  3. We have been working for several months in adding Javadocs to the most important classes and methods as part of the development of 6.1. To be truely honest, the progress of this effort has been slow because we want to make sure the documentation is very consistent and always up to date which requires starting slow to set the right patterns.
  4. We have created new tools to generate more reference documentation automatically, including taglibs, XML documents and the portal.properties files. We also plan to build some new tools for additional reference documentation.


As you all know we are still an small company in comparison to some of our competitors and that limits our ability to improve in this area as far as we would want to. But I wanted to let you know that we really care about this and we are doing our very best towards this end.

We appreciate a lot the fact that you guys give us all this feedback so that we don't forget what is important emoticon
Jorge Ferrer
RE: Poll Results: Community in 2011
2011/02/05 7:08
答え

Jorge Ferrer

LIFERAY STAFF

ランク: Liferay Legend

投稿: 2764

参加年月日: 2006/08/31

最近の投稿

Hey Denis,

Have you read the chapter in the Administration Guide about the web content management?
http://www.liferay.com/es/documentation/liferay-portal/6.0/administration/-/ai/building-a-site-with-liferay-s-wcm
Denis Signoretto
RE: Poll Results: Community in 2011
2011/02/07 13:50
答え

Denis Signoretto

ランク: Regular Member

投稿: 220

参加年月日: 2009/04/21

最近の投稿

Hi Jorge,

thanks for the information. I didn't see it before. I have just (quickly) read it and it seams a good starting point. Thanks to share it with us.

Denis.
Sheikh Sajid
RE: Poll Results: Community in 2011
2011/02/10 21:23
答え

Sheikh Sajid

ランク: New Member

投稿: 17

参加年月日: 2010/10/04

最近の投稿

Great Stuff, James!!! Keep it up!!
I would like to suggest to prepare a process for Liferay community users to contribute to your efforts in documentation (wiki is good but not good enough).

Thanks a ton for the stuff you are delivering.
James Falkner
RE: Poll Results: Community in 2011
2011/02/11 4:15
答え

James Falkner

LIFERAY STAFF

ランク: Liferay Legend

投稿: 1325

参加年月日: 2010/09/17

最近の投稿

What did you have in mind?
Andrius Kurtinaitis
RE: Poll Results: Community in 2011
2011/02/11 5:41
答え

Andrius Kurtinaitis

ランク: Junior Member

投稿: 62

参加年月日: 2010/01/24

最近の投稿

James Falkner:

With "Developer Documention" being the clear winner, what kinds of developer documentation do you want to see?

I miss a description of liferay architecture.

I know, there is something already put down, like
http://www.liferay.com/community/wiki/-/wiki/Main/Logical+Architecture

But this text is a very very very high level description talking about clouds, networks and MDA. There is no clear text talking about real technical questions like:
- use of classloaders in liferay core
- where and how is hibernate used, where and why its functionality is replaced by custom implementation
- where and how is spring used
- how logging works and how to make logging work when using other logging libraries
- and others
Andrius Kurtinaitis
RE: Poll Results: Community in 2011
2011/02/22 0:13
答え

Andrius Kurtinaitis

ランク: Junior Member

投稿: 62

参加年月日: 2010/01/24

最近の投稿

Additional points for developer documentation:
1. Internal logic of Liferay data model - entities have several identifiers (id, uuid, primary key, resourcePK). It is not obvious:
- when are they used?
- how are they used to relate different entities?
2. AlloyUI developer documentation consists of a (unfinished) series of Nathans blog entries. Could you please ask him to continue with it?
:-)
Corné Aussems
RE: Poll Results: Community in 2011
2011/02/23 14:28
答え

Corné Aussems

ランク: Liferay Legend

投稿: 1284

参加年月日: 2006/10/03

最近の投稿

Somewhat inspired by the fact that a relatively large number of members from 1 particular small country are participating in the 100 Papercuts Program ;)

I think i would be interesting to see some statistics on the demographics of Liferay members.
James Falkner
RE: Poll Results: Community in 2011
2011/03/01 8:13
答え

James Falkner

LIFERAY STAFF

ランク: Liferay Legend

投稿: 1325

参加年月日: 2010/09/17

最近の投稿

Andrius Kurtinaitis:
Additional points for developer documentation:
1. Internal logic of Liferay data model - entities have several identifiers (id, uuid, primary key, resourcePK). It is not obvious:
- when are they used?
- how are they used to relate different entities?
2. AlloyUI developer documentation consists of a (unfinished) series of Nathans blog entries. Could you please ask him to continue with it?
:-)


Related to your first item on internal logic, Jorge is going to publish a new version of the Developer's Guide very soon that covers at least this aspect, and adds much in other areas, thanks to community feedback like this (and others as part of the Liferay Community Leadership program).