Improving the wikiImproving the wikihttps://liferay.dev/en/c/message_boards/find_thread?p_l_id=119785333&threadId=42748072024-03-29T12:41:50Z2024-03-29T12:41:50ZRE: Improving the wikiSenthil Chockalingamhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=51812532010-06-28T12:26:46Z2010-06-28T12:26:46ZDear Team,<br /><br /><br />we've gave <strong>view</strong> permission for the end user to access the WIKI, But that user can <span style="font-size: 24px;"><strong>Edit</strong><span style="font-size: 24px;"></span></span> the Wiki and he can <strong>revert</strong> the previous Version also<strong>(i.e for end user revert option also working). </strong>Please help us on.<br /><br /><br /><br />Actually i want only give the View Access to End User. And for particualr user i want to give updated permission. it's is possible to keep the Revert option for Admin(Owner)?<br /> this.<img alt="emoticon" src="@theme_images_path@/emoticons/blink.gif" ><img alt="emoticon" src="@theme_images_path@/emoticons/blink.gif" >Senthil Chockalingam2010-06-28T12:26:46ZRE: Improving the wikiLisa Simpsonhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=43449072009-12-03T21:13:30Z2009-12-03T21:13:30ZI think that from the community perspective we don't always understand the differences between the versions. I know that for me, I've tried to help people who were using 4.X stuff and only frustrated them. My experience has been with the 5.1.X and later. It's very hard for me, as non-devloper community member, to know that what I am writing is specific to my version or not.<br /><br />I know that when I write things, I do try to put the version information in it so that if its pertinent, it gets shown.Lisa Simpson2009-12-03T21:13:30ZRE: Improving the wikiJorge Ferrerhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=43405732009-12-02T19:22:49Z2009-12-02T19:22:49ZHi Lisa,<br /><br />We've sat down and thought about this before. What we decided to do is:<br /><ul><li>If the changes between versions are minor just highlight them as comments in the same page</li><li>If the changes are large create separate versions for each version including the version number in the title and make both pages children of a parent page that has an introduction to the topic as well as any common information</li></ul><br /><br />Each of the resulting pages should have appropriate tags to identify which versions are being considered by the authors.<br /><br />This approach has worked quite well when it's been used. Unfortunately there were many articles which were not following it and we haven't had time to review the existing articles. This is where we really need help from the community to increase the quality of the wiki.Jorge Ferrer2009-12-02T19:22:49ZRE: Improving the wikiLisa Simpsonhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=43397882009-12-02T15:55:53Z2009-12-02T15:55:53ZThe wiki pages aren't as valid for each version as you're assuming. There are subtle differences between 5.2.3 and 5.2.1 even for basic things like the control panel. Copying the page for that from 5.2.1 to 5.2.2 and then 5.2.3 actually leaves room for it to be customized for that version. Categories aren't always that useful. We've been trying to use them in our own LR stuff and I have to tell you that it's not going very well. It's a bit more cumbersome. If you mean categories like the message board has, that might work better.Lisa Simpson2009-12-02T15:55:53ZRE: Improving the wikiJorge Ferrerhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=43039222009-11-21T11:26:27Z2009-11-21T11:26:27ZHi Lisa,<br /><br />Being to filter by version is certainly a great idea. What makes it harder is that most wiki pages are valid for several versions, not only one. Also, a lot of them don't say explicitly for which version are they valid for (although that can be solved if enough of us volunteer to do a review).<br /><br />In any case, assuming we set the version to all articles, we should find a way to be able to filter by that information. I think nodes is a valid approach but I find some issues with it. I've been thinking about it and I have a proposal: to use categories and allow filtering by categories after doing the search. It would work similar to a faceted search, allowing users even to select several of them.<br /><br />This is not something that the wiki allows right now, but we are probably on time to add this functionality for 5.3. That means that it won't be used for liferay.com for several months but we can all work on it together to make sure when it gets to liferay.com it has everything we're discussing in this thread. <br /><br />The same could be done for the message boards.Jorge Ferrer2009-11-21T11:26:27ZRE: Improving the wikiLisa Simpsonhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=43035902009-11-21T06:52:01Z2009-11-21T06:52:01ZI really think that you guys should reach out to the community to help you with the policing. I hear you about the knowledge base portlet but honestly, the search stuff needs to have options. It shouldnt' always be global. If I'm searching for a post I saw in the forums, I don't give a whisker about wiki articles or web content. I just want to find that one post. <br /><br />And the wiki search right now returns so *much* stuff that its overwhelming and then to make things worse, a lot of the results are for previous versions. Google really does do a better job of searching your site and producing relevant results. Which I why I suggested creating a node which could house all of the previous version stuff. That makes has the effect of limiting the search results by version. And I was hoping that information could be moved between nodes? I guess that's not the case. <br /><br />You would never have more than the 5 nodes that I listed. <br /><br />Under my proposed scheme you would currently have the following nodes:<br /><br /><br />How to Contribute<br />Previous Versions<br />5.2.3 (Current Version)<br />5.3 (Upcoming Version)<br />Proposals (Improvements)<br /><br />Under Previous Versions you would have all the 4.X stuff, which I have to tell you drives me bonkers when I'm searching for 5.X stuff. You would also be able to move the 5.1.X and 5.2.1 and 5.2.2 specific stuff under previous versions. Then when 5.3 is out, that would be come the Current Version and 5.2.3 would roll under the Previous Versions documentation. And 5.3.1 would be the Upcoming Version. Since you're changing your versioning - Release Candidate, Early Adopters, General Availability or Enterprise Edition - it would look some thing like this. RC's, Alpha's, Beta's, Gamma's, etc. would be "Upcoming Versions". <br /><br />So after the 5.3 release you would have the following nodes:<br /><br />How to Contribute<br />Previous Versions<br />Current Version<br />-> General Availability<br />-> EE<br />Upcoming Version<br />-> Release Candidate<br />-> Early Adopter<br />ProposalsLisa Simpson2009-11-21T06:52:01ZRE: Improving the wikiJorge Ferrerhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=42888502009-11-17T21:10:53Z2009-11-17T21:10:53ZHi Jakub,<br /><br />Thanks for your feedback.<br /><br />I agree that the current way of searching is part of the problem. And we've also tried to find a solution for it in the new version of the site. Specifically it will debut a new global search that will allow searching at once in all the sources of information including: web content, message boards, knowledge base and wiki.<br /><br />Regarding the official documentation being so version specific, that should not be the case in general. For example, the documentation for 5.2 should be true for all its stable minor versions. What has happened in the past though is that we haven't properly labelled the initial releases as meant for early adopters (for example 5.2.0 and 5.2.1) and thus yet undocumented and subject to change. That's exactly what happened with the database configuration mechanism which changed the default from using the datasource configuration of each application server to a general method that is the same for all application servers.<br /><br />In 5.3 we'll fix this by adding a qualifier to minor releases to indicate its readiness (for example if it's a Release Candidate, Early Adopters, General Availability or Enterprise Edition). The official documentation will be published around the time the GA or EE releases come out.<br /><br />We will be posting blog entries to explain all this in the following months so I'd recommend subscribing to them to every ones who is not yet following them.<br /><br />Also, we'd be glad to keep receiving feedback through this or other threads in the "Liferay's Community" category.Jorge Ferrer2009-11-17T21:10:53ZRE: Improving the wikiJ Bhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=42886932009-11-17T19:43:43Z2009-11-17T19:43:43ZJorge,<br /><br />Just sounds like the problem is going to become the same, the 'official' documentation will get put into yet another location (or repository for knowledge). That will NOT be searchable via the WIKI (where most users will go to).<br /><br />Currently the BIGGEST issue for me with Liferay, is that it is lacking big time in documentation, and the official documentation is SO version specific, that items in 5.2.1, are no longer in the same in 5.2.3, etc;<br /><br />My company has tried rolling out Liferay, and just setting up the MYSQL DB, took over 6 hours of tinkering! In the end we found notes on how to do it properly by GOOGLING, and finding a blog of someone who was equally frustrated and just documented their process, a lot more clearly.<br /><br />Later, our experience was different. A collegue and I took part in training for the Admin/Developer classes, during the class we learned in 4 min how to setup the MYSQL DB another way. Which both made us think "WTF!? Why wasn't this documented to begin with, we had to take the class to learn it properly!".<br /><br />I would agree with Lisa, re-do the WIKI, build your documentation in one place, call for community input, and police the structure. And fix that search...J B2009-11-17T19:43:43ZRE: Improving the wikiJuan Fernándezhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=42864532009-11-17T11:03:48Z2009-11-17T11:03:48Zok... that sounds much better! <img alt="emoticon" src="@theme_images_path@/emoticons/happy.gif" >Juan Fernández2009-11-17T11:03:48ZRE: Improving the wikiJorge Ferrerhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=42862462009-11-17T10:10:46Z2009-11-17T10:10:46ZHi Juan,<br /><br />We are already working on another solution for that problem. In the next few weeks we'll launch a new site that will be using a new portlet (the Knowledge Base) to automatically publish the official books to HTML into the site. It will also allow commenting, tagging and rating sections. In fact each section will have its own page which will make it much easier to link to them from the forums or wiki.<br /><br />That way we keep the benefits of the official documentation which is properly edited and verified by Liferay engineers with the benefit of the wiki which is always evolving and up to the latest improvements.Jorge Ferrer2009-11-17T10:10:46ZRE: Improving the wikiJuan Fernándezhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=42861362009-11-17T09:56:08Z2009-11-17T09:56:08ZHi Jorge:<br /><br /><div class="quote-title">Jorge Ferrer:</div><blockquote><br />1) The wiki is not meant to store the official documentation. That means that it doesn't need to have a complete table of contents and it should link to the official documentation whenever possible.<br /></blockquote><br /><br />I don't understand this point... dind't you say that the official documentation was unsearchable 'cos it was in pdf? <br />I think that having all that information in the wiki would make it much more accessible and linkable to forum posts and other wiki articles, even if it wouldn't be "official".<br /><br />Regards<br />Juan FernándezJuan Fernández2009-11-17T09:56:08ZRE: Improving the wikiJorge Ferrerhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=42859622009-11-17T09:32:25Z2009-11-17T09:32:25ZHi Lisa,<br /><br />Thanks for all your comments.<br /><br />Regarding the wiki issue, I'm not sure I understand the details, but it sounds like a bug, Can you file a bug in JIRA with details on how to reproduce it?<br /><br />Regarding the re-organization I agree, let's coordinate it through this thread before we start doing anything. As I mentioned above the rules that I have in mind right now are:<br /><br />1) The wiki is not meant to store the official documentation. That means that it doesn't need to have a complete table of contents and it should link to the official documentation whenever possible.<br /><br />2) Wiki articles should be interlinked as much as possible. The names of the articles should be based on concepts to encourage and facilitate linking.<br /><br />3) There should be a parent wiki article for each Liferay portlet and tool that should have children or links to any other article related to it. This is the area where we're stuck right now and we would really welcome help.<br /><br />4) All articles should indicate which version of Liferay are they targetted to and at least a tag of one of the 6 main categories. I propose to coordinate an effort to review all existing wiki articles and make sure this is true for all.<br /><br />Regarding creating nodes, I agree that we could use them to organize the wiki better, but I would be careful with creating too many. The reason is that searching across all would be much harder and linking between wiki articles of different nodes has to be manual. I would suggest keeping the 2 we have right now and creating a third about "Contributing to Liferay". Let's see how this goes first and we can consider creating others later as we see fit.<br /><br />Thoughts?Jorge Ferrer2009-11-17T09:32:25ZRE: Improving the wikiLisa Simpsonhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=42834312009-11-16T22:36:21Z2009-11-16T22:36:21ZIt leaves the link on the old parent page and that's where a lot of the confusion comes from. There needs to be a move *and* a rename function. One should leave the link on the old parent and one should not. Leaving behind all the detirus from pages that weren't created in the proper places is a big cause of the current state of the wiki and my comment about the sock-drawer. Anyone with a child knows what I'm talking about though. You come in, clean it up, and two weeks later your kid can't find two socks of the same color to save their lives.<br /><br />And I'm quite happy to help to create it, move content, etc. but it is the Liferay wiki and I don't feel quite right about just bopping in and taking over without at least asking for permission <img alt="emoticon" src="@theme_images_path@/emoticons/happy.gif" > I'm even happy to read through it and move things around to help keep it organized properly. People do create things in wrong places for a variety of reasons and it takes some policing to keep it all sorted out. I know that you guys are a small company working on an open source project. Documentation, though, is one of the places were I can really help you. No developer likes to do documentation. <br /><br />I'm a professional geek by trade and have been told on more than one occasion that I'm an alpha geek. I've got a very strong background in network security, which also involves producing lots of documentation and keeping that documentation sane and organized. <br /><br />As to what I was thinking in that doucment.... <br /><br />In the site map that I sent you, I think those top level things would be "nodes". I think that would help immensely with the searching since the searches seem to limit themselves to a single node. <br /><br />How to Contribute would be a node. Previous Versions would be a node. Current Versions would be a node as would Upcoming Versions and Proposed Improvements (which is currently a node). <br /><br />That way when you search in Current Versions, you don't pull in a lot of dated information from previous versions.Lisa Simpson2009-11-16T22:36:21ZRE: Improving the wikiJorge Ferrerhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=42833402009-11-16T22:15:41Z2009-11-16T22:15:41ZHi Lisa,<br /><br />What do you mean by "easier to move"?<br /><br />If it's categories it's as easy as editing the page and changing the tags (we'll be differentiating tags and categories as soon as we upgrade liferay.com to 5.2). If it's parent-child relationships or page titles that's also easy through Details >> Move<br /><br />What else would you want?Jorge Ferrer2009-11-16T22:15:41ZRE: Improving the wikiLisa Simpsonhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=42833192009-11-16T22:11:33Z2009-11-16T22:11:33ZI'm going to chime in here... Honestly, if it were easier to move misplaced pages around in your Wiki portlet, it would be less of a problem. That way, if someone created a page in the wrong place, one of the wiki moderators could move it to where it ought to be. I've offered to create the structure and help police it. Wiki's, like message boards, need to be moderated. Otherwise you get stuff posted all over willy-nilly.Lisa Simpson2009-11-16T22:11:33ZRE: Improving the wikiJuan Fernándezhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=42804332009-11-16T11:15:24Z2009-11-16T11:15:24ZHi Jorge:<br />I think this is a really important issue to improve Liferay as a commercial product: with no information/documentation you are nothing, and this can be the best marketing tool because one the most important drawbacks of Liferay is the difficulty to search doc...so I encourage Liferay team to go on with this. <br /><br /> <div class="quote-title">Jorge Ferrer:</div><blockquote><br />1) The official documentation is only in PDF form which means that it doesn't appear in searches. This is pretty bad since many people don't even realize that it exists when it's probably the most valuable source of information in the site.<br /></blockquote><br /><br />I propose something: why don't you copy the pdf text and format it according to the new wiki organization? It would not be that hard work and it would make it much more accessible.<br /><br /> <div class="quote-title">Jorge Ferrer:</div><blockquote><br />4) There is a clear need for basic information about the portlets provided by Liferay. IMHO this is one of the reasons why it's so hard to connect the lines between all the articles. If we had this basic information in place it would be much easier to link new articles to it.<br /><br />What we've done so far on this can be seen in: <br /><a href="http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/Liferay+Portlets">http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/Liferay+Portlets</a><br /><br /></blockquote><br /><br />This is one of the most important issues to fix, because new people are quite lost: what is this portlet for? How can I do this?(when it already exist)... I think that wiki page is a good start, but we have to link there ALL the information we have related to every portlet.<br /><br /><div class="quote-title">Jorge Ferrer:</div><blockquote><br />4) Do whatever activities we can think of to communicate this structure to the community so that they contribute to the wiki even more than now, while keeping in mind this organization.<br /></blockquote><br /><br />It is very important to get the community involved in this process, but it would be great to see more commitment from the company members in the forum, documentation... I have asked several questions that the Liferay team knows and I have not had answers from the team...and it's a pity to see so many unanswered questions out there<br /><br />And a last question: what is the reason of this lack of documentation? why there aren't class diagrams, database analysis, use cases? I think that is important for the developers<br /><br />Well, I'll help as much as I can in this process<br />Regards<br />Juan FernándezJuan Fernández2009-11-16T11:15:24ZRE: Improving the wikiJorge Ferrerhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=42749032009-11-13T14:00:43Z2009-11-13T14:00:43ZOur initial attempt was to create a very well defined table of contents (actually it was quite similar to what you are suggesting) and did our best to encourage people to use it. It didn't work. We tried to make it easier, write more information about how to contribute, etc. Again it failed. People started creating their own table of contents for their own wiki pages.<br /><br />We talked long about how to do this and we decided to follow the two-parts strategy:<br /><br />A ) The official documentation would follow a pretty well defined TOC and would be coordinated by Rich by writting specific content or reusing content from the wiki if considered appropriate. This is the equivalent of the Drupal documentation that you've pointed to.<br /><br />B ) The wiki would be organized in the form of loosely connected articles about specific topics not covered in the official docs. They would be community contributed and organized into 6 main categories (and some subcategories that were later removed for simplicity). It was also decided that articles should be short and the titles concepts as opposed to actions so that there were more opportunities for reusing by linking in the true wiki style.<br /><br /><a href="http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/How+To+Make+Wiki+Articles">http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/How+To+Make+Wiki+Articles</a><br /><br />This strategy definitely improved the situation but there are also some problems that we've detected. Here are some of them:<br /><br />1) The official documentation is only in PDF form which means that it doesn't appear in searches. This is pretty bad since many people don't even realize that it exists when it's probably the most valuable source of information in the site.<br /><br />2) We tried to encourage wiki pages creation through links, as the Wikipedia does, but it turns out most people didn't know how to do this. As a result easier methods to add new pages were created and now they are mostly isolated.<br /><br />3) The wiki search functionality is not working properly. We've done some improvements and it's slightly better now, but it's still not good enough.<br /><br />4) There is a clear need for basic information about the portlets provided by Liferay. IMHO this is one of the reasons why it's so hard to connect the lines between all the articles. If we had this basic information in place it would be much easier to link new articles to it.<br /><br />What we've done so far on this can be seen in: <br /><a href="http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/Liferay+Portlets">http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/Liferay+Portlets</a><br /><br />It would be of tremendous help if more people could help doing this. Once this is done we wanted to try to do a full review of all the existing articles and try to:<br />1) Rename them so that the titles are concepts whenever possible (to make it easier to link them)<br />2) Use parent-child relationships to group articles about related portlets or portal features<br />3) Link articles between them as much as possible<br />4) Do whatever activities we can think of to communicate this structure to the community so that they contribute to the wiki even more than now, while keeping in mind this organization.Jorge Ferrer2009-11-13T14:00:43ZImproving the wikiJorge Ferrerhttps://liferay.dev/en/c/message_boards/find_message?p_l_id=119785333&messageId=42748062009-11-13T13:24:50Z2009-11-13T13:24:50ZI'm creating this new thread as an answer to a post in another thread by Lisa Simpson:<br /><br /><blockquote><br />Just so you don't think that all I do is gripe without contributing, I'm proposing <a href="http://docs.google.com/View?id=djwsnk6_2hgr6gdf2">the following site map for your wiki</a>. I'd like to see the community discuss it. I'm sure that I've missed some stuff but I feel certain that the rest of the community will be able to fill in those gaps. I'm just not sure of the best way to post it for people to be able to comment on it. <br /><br /><ul><li>Improving the wiki will be good because people might start to use if they understand it better. The search in the wiki isn't much better than the search in the message boards. Its great that it pulls up 500 results but when 497 are not relevant, it's annoying, not useful. A big part of this is because of the way that the wiki is organized, which is is to say that it's really not. It's grown organically over time. Ok for starting out but not what one wants to see from a project billing itself as "Enterprise"</li><li>Its really not clear where to put documentation when you write in it. Tha