Vista Combinata Vista Piatta Vista ad Albero
Discussioni [ Precedente | Successivo ]
toggle
James Falkner
Poll Results: Community in 2011
3 febbraio 2011 11.01
Risposta

James Falkner

LIFERAY STAFF

Punteggio: Liferay Legend

Messaggi: 1370

Data di Iscrizione: 17 settembre 2010

Messaggi recenti

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!
Allegato

Allegati: Screen shot 2011-02-03 at 1.24.42 PM.png (73,6k)
Joel Peterson
RE: Poll Results: Community in 2011
3 febbraio 2011 16.58
Risposta

Joel Peterson

Punteggio: New Member

Messaggi: 22

Data di Iscrizione: 18 febbraio 2010

Messaggi recenti

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
3 febbraio 2011 17.29
Risposta

chris anderson

Punteggio: New Member

Messaggi: 9

Data di Iscrizione: 9 aprile 2010

Messaggi recenti

(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
4 febbraio 2011 8.43
Risposta

James Falkner

LIFERAY STAFF

Punteggio: Liferay Legend

Messaggi: 1370

Data di Iscrizione: 17 settembre 2010

Messaggi recenti

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
4 febbraio 2011 9.57
Risposta

Tobias Käfer

Punteggio: Regular Member

Messaggi: 128

Data di Iscrizione: 28 marzo 2008

Messaggi recenti

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
5 febbraio 2011 0.52
Risposta

Denis Signoretto

Punteggio: Expert

Messaggi: 261

Data di Iscrizione: 21 aprile 2009

Messaggi recenti

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
5 febbraio 2011 7.06
Risposta

Jorge Ferrer

LIFERAY STAFF

Punteggio: Liferay Legend

Messaggi: 2764

Data di Iscrizione: 31 agosto 2006

Messaggi recenti

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
5 febbraio 2011 7.08
Risposta

Jorge Ferrer

LIFERAY STAFF

Punteggio: Liferay Legend

Messaggi: 2764

Data di Iscrizione: 31 agosto 2006

Messaggi recenti

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
7 febbraio 2011 13.50
Risposta

Denis Signoretto

Punteggio: Expert

Messaggi: 261

Data di Iscrizione: 21 aprile 2009

Messaggi recenti

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
10 febbraio 2011 21.23
Risposta

Sheikh Sajid

Punteggio: New Member

Messaggi: 17

Data di Iscrizione: 4 ottobre 2010

Messaggi recenti

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
11 febbraio 2011 4.15
Risposta

James Falkner

LIFERAY STAFF

Punteggio: Liferay Legend

Messaggi: 1370

Data di Iscrizione: 17 settembre 2010

Messaggi recenti

What did you have in mind?
Andrius Kurtinaitis
RE: Poll Results: Community in 2011
11 febbraio 2011 5.41
Risposta

Andrius Kurtinaitis

Punteggio: Junior Member

Messaggi: 62

Data di Iscrizione: 24 gennaio 2010

Messaggi recenti

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
22 febbraio 2011 0.13
Risposta

Andrius Kurtinaitis

Punteggio: Junior Member

Messaggi: 62

Data di Iscrizione: 24 gennaio 2010

Messaggi recenti

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
23 febbraio 2011 14.28
Risposta

Corné Aussems

Punteggio: Liferay Legend

Messaggi: 1289

Data di Iscrizione: 3 ottobre 2006

Messaggi recenti

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
1 marzo 2011 8.13
Risposta

James Falkner

LIFERAY STAFF

Punteggio: Liferay Legend

Messaggi: 1370

Data di Iscrizione: 17 settembre 2010

Messaggi recenti

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).