Liferay Community Documentation Cleanup!!! JOIN IN!

[Samuel Liu, geändert vor 13 Jahren.]

Help us improve the wiki! Read the instructions below for how to do it!

Hi everyone!

So we're currently organizing a community-wide documentation cleanup, and we would love your help. We hear the pain of community members: documentation is not organized right now. To fix this problem, we need volunteers!

[indent]Task #1
We need to go through the entire wiki and tag every article with a version number (or multiple version numbers)!

Our developers are going to make use of the categories feature of our wiki and categorize all wiki articles by version programmically. Instead of creating multiple separate wikis, we decided to do this because some articles do apply to more than one version, and to maintain parallel articles with the same content is impractical.

Before we can categorize, we need to tag the posts. We're going use some commands to convert the tags to categories, you see, so this is the most efficient thing to do.

So what we need everyone to do *right now* is to go through wiki articles, find the untagged/mistagged ones, edit, and add a tag.

EXAMPLE:

Problem: "Hmm. This article is for Liferay 5.2 but it doesn't say that, and I tried to use it for Liferay 6. This is a problem"

Solution: "Edit" -> liferay v5.2 -> "Add Tag"

When you add a tag, please make sure the version is 5.2 and not 5.2.3. In the same way, make sure the version number is 6.0 and not 6.0.2. A version number should be one digit referring to the major release, a dot, and another digit referring to the minor release. If you see anything differing from this standard, please change it!

[/indent]

If you do edit some pages or plan on helping out, please post a reply here so that we can get a good idea of how much community help we're getting. It's helpful and encouraging to us because then we know we can launch some bigger community initiatives to help improve Liferay. We're trying to bring about real change in problems that users have identified.

Thanks for being part of this community, we really appreciate all of you

Special hattip to Shagul, Tobias, Simon, and Fastbob for helping to bring this about last week. We really value your input and the time you all spend giving it.

Warm regards,
Sam

[Samuel Liu, geändert vor 13 Jahren.]

[indent]TASK #2
Help us to complete the page about Liferay Portlets to make sure we have at least one page for each of our portlets: Liferay Portlets Wiki

For example, at this time we have no page for WSRP! If anyone is an expert at that please fill it in. Also if you see that a portlet is specific to a Liferay version, it would be good to mention it on the page.

Please strive to keep everything organized: here are instructions for how to write a good wiki article:
Wiki Guidelines (FOLLOW THESE PLEASE)

[/indent]

[Samuel Liu, geändert vor 13 Jahren.]

[indent]TASK #3!

Please help review the existing pages to improve them following the guidelines and specifically:

• Add links to other related pages
  [indent](e.g make articles "children" if appropriate, and show "related links" in your articles!)[/indent]

EDIT: Sorry guys, didn't realize non-administrators couldn't carry out most of the original tasks here. Still this is important -- if you get a chance, Task #1 is highest priority
[/indent]

[Samuel Liu, geändert vor 13 Jahren.]

Status Update from our Wiki Crew
--------------------------------
Today we are brainstorming and using google docs to organize the substructure of the wiki. The goal is to categorize certain pages as children of certain other pages, and to link related pages to each other in a tight-knit way so that users can find the information they want.

Yesterday we reformatted some of the wiki's style, so that it is easier to read. Hope you notice that headings (h2, h3, h4) have been restyled and margins are more like Wikipedia for readability.

To the community: please help us with tasks #1,2,3 as they will be vital when we reach the stage for implementing categories!

Your friendly community advocate,
Sam

[Corné A, geändert vor 13 Jahren.]

I will join your quest and will at first begin with my own started wiki's and the ones i stumble upon.

If you share your (googledocs)todo list maybe you could strike off some already done.

or you have subscribed yourself to all Wiki's like me and then you'll see all changes

[Samuel Liu, geändert vor 13 Jahren.]

HAHA wow corne,

That's a good idea too. We don't really have a todo list right now aside from this one, but you're right a googledocs is a good idea. We'll share it as soon as we get it created!!!

Congrats on being the first to join our noble quest.

Community Members Helping So Far:
1. Corne

Okay we need some more!

[Corné A, geändert vor 13 Jahren.]

Edited and posted to remember myself;

http://www.liferay.com/community/wiki/-/wiki/Main/Translating+Liferay+to+a+New+Language/maximized

http://www.liferay.com/community/wiki/-/wiki/Main/Liferay+Translation+Team

http://www.liferay.com/community/wiki/-/wiki/Main/Performance

[Simon Gołębiewski, geändert vor 13 Jahren.]

Samuel Liu:

Before we can categorize, we need to tag the posts. We're going use some commands to convert the tags to categories, you see, so this is the most efficient thing to do.

Warm regards,
Sam

Sam,

1. I tried adding categories but there are so many that it took 35 second to load them all. There are so obsolete ones like "Partner-Type". Please change permision for this vocabulary to show them only for Liferay staff not for all users.

2. Curently tagging wiki pages is also very hard to use.
First problem is that suggestion will kick in after entering first letter. This is bad idea beacuse what good suggestion I can get from one letter??? It just slows the whole process. In most systems such suggestion will show up after user enters 3 letters at least.
Second thing is background of suggestion box. On my Firefox 3.6 it's transparent (see attachement)!
Third thing is that ajaxt suggestion you use on liferay.com is not very fast.
I see that points 1 and 3 are fixed (http://issues.liferay.com/browse/LPS-4854).

Is there any chance we can get at least nr.1 working on Liferay.com ?

3. can we show on page its "last modified" date? From usability point of view separate "details" page is not so good idea.

4. How should we manage deletion of obsolete pages? For example User your email account as SMTP server with Tomcat. I want to change this page name to "Email configuration" and add section about how to do it in LR 6.0. There is no way to change page title. My proposal for such process is:

• Add NEW wiki page with proper title
• Add content on NEW wiki page
• Tag and categorize NEW page - in what wiki section your page will be displayed depends on TAGS)
• Remove tags from OLD page - this way it won't show in wiki sections
• Remove content from OLD page - google will not show it in its results (and we want that!)
• On OLD page paste such formula "This page was moved to <new_page_link>" where <new_page_link> is a link to your new wiki page. This way people that bookmarked this page won't be confused about it deletion.

How about that?

Cheers,
Szymon

[Samuel Liu, geändert vor 13 Jahren.]

Hi Simon,

Thanks for all the helpful comments! I noticed the same problems myself.

1. We didn't enable categories except to admin (in fact I don't have the permissions myself) -- there are probably reasons for this but right now we aren't using categories. Instead, we are using tags to add "version" tags to each post. Later, our developers will convert the tags to actual categories in the SQL.

2,3. I know, it takes so long to load. This and #3 are beyond my control right now though, because they require improvements to the wiki portlet in general and I don't know if anyone can work on those at least in the very present. I will bring those up to the right people and try to get it fixed as soon as possible though. So far I've been just patiently putting in the tags despite the slow speed You know what I will try my best to get someone to fix it!!!

4. Since deletion can only be done by admins, do me a favor and write "Marked for Deletion - [the resason]" and go ahead and make any changes that you might have done otherwise. You can also tag as "marked for deletion" but tags are slow right now. We will get to it when we start reformatting post contents.

So for your steps

1. Add NEW wiki page with proper title
2. Add content on NEW wiki page
3. Tag and categorize NEW page - in what wiki section your page will be displayed depends on TAGS)
4. Remove tags from OLD page - this way it won't show in wiki sections
5. Remove content from OLD page - google will not show it in its results (and we want that!)
6. On OLD page paste such formula "This page was moved to <new_page_link>" where <new_page_link> is a link to your new wiki page. This way people that bookmarked this page won't be confused about it deletion.

I can do #4-6 by deleting the page. When I delete a page, it automatically does the "This page was moved to <new_page_link>" thing You and others can help us by doing #1-3. It'd make our jobs even easier if you posted here which ones you want me to delete -- I will do it super fast that way, just for you haha

Thanks so much!! I don't know what we'd do without people to help, the wiki is in need of improvement for sure.

Me and another coworker are currently trying to structure the wiki articles as a tree so that every article is linked to another at least in some way. In doing this we will weed out the bad ones too.

Keep up the great work and help! Thanks Corne also for your help.

Warm regards,
Sam

[Simon Gołębiewski, geändert vor 13 Jahren.]

Samuel Liu:

1. We didn't enable categories except to admin (in fact I don't have the permissions myself) -- there are probably reasons for this but right now we aren't using categories. Instead, we are using tags to add "version" tags to each post. Later, our developers will convert the tags to actual categories in the SQL.

Hmm better check that again Sam beacuse I've just added new category to old wiki page (see attachement). If we want to use only tags it will be better if you correct Wiki guidelines beacuse you wrote in several places "Categories" instead of "tags". For example:
"We have created a set of categories to help identify the topic of every wiki page. These categories are: "

Samuel Liu:

2,3. I know, it takes so long to load. This and #3 are beyond my control right now though, because they require improvements to the wiki portlet in general and I don't know if anyone can work on those at least in the very present. I will bring those up to the right people and try to get it fixed as soon as possible though. So far I've been just patiently putting in the tags despite the slow speed You know what I will try my best to get someone to fix it!!!

"3 letter suggestion" and "transparent background" are "must-have!" improvements. Those bugs discourages people from editing wiki

[Corné A, geändert vor 13 Jahren.]

TIP: since Google Chrome is a lot faster with javascript the waiting for categories is just/almost bearable.

[Samuel Liu, geändert vor 13 Jahren.]

Thanks Corne,

The lead UI guy told me that you can type the tag into the field above it, copy the whole word, and paste it into the box if you don't want it to give you completion either. Far from optimal, I know, but also more bearable than what we have. It's something about synchronous AJAX (which is kind of bad...since the idea of AJAX is asynchronous to begin with) which is locking up the UI while Liferay thinks.

I'm so sorry about this guys, we are doing our best with what we have right now until we come up with something better though. Thanks for all the feedback and support!

Warm regards,
Sam

Updated Wiki Volunteer List
------------------------
1. Corne
2. Simon

Thanks guys!

[Samuel Liu, geändert vor 13 Jahren.]

UPDATE

See updated Wiki Guidelines -- instead of using categories, PLEASE USE TAGS!

Thanks!
Liferay Wiki Crew

[Samuel Liu, geändert vor 13 Jahren.]

Progress Update
------------------
Further changes are being made to the wiki. For the coming week, the wiki will undergo tree-style restructuring as we organize pages into children/parents.

A deletion policy was added to the Wiki Guidelines. If you think a page should be deleted, please edit the article and place at the top

// This article is pending deletion because _____reason here_______. For more information, please refer to the [[http://www.liferay.com/community/wiki/-/wiki/Main/Wiki+Guidelines#section-Wiki+Guidelines-DeletionPolicy | Deletion Policy]] //

[Samuel Liu, geändert vor 13 Jahren.]

General Update
-----------------
Transparent background in tagging is fixed. Unfortunately the tagging slowness in Firefox is still present -- for the time being please use Google Chrome to get around it. Alternatively you can type your tag elsewhere and paste it in. We are working on that issue!

Warm regards,
Sam

[Simon Gołębiewski, geändert vor 13 Jahren.]

Sam,

Here is my little proposal about tagging. Please revise:

Tags you should use when correcting wiki page:
Required:

• Wiki section tags: to what wiki sections this page belongs to e.g. using liferay, development, installation
• Liferay version tags: e.g. liferay 5.2, liferay 6.0

Additional you can use:

• Liferay product tag: liferay ide, alloy ui, liferay ee, social office
• Portlet tag: use official portlet names e.g. activities portlet, document library display portlet
• Liferay functionality tag: e.g. web content, blogs, social equity, forum, permissions, community, organizations, software catalog, polls, wiki
• "Related to" tags: used when page topic is related to things like cache, performance, maven, eclipse, svn, tomcat, alfresco, oracle

Also I have a question: should we use "liferay v6.0" or "liferay 6.0" ?

[Samuel Liu, geändert vor 13 Jahren.]

Hi Simon,

Great input. Thanks as always --

You should use liferay v6.0 instead of liferay 6.0.

I think I'm going to add most of your tag suggestions to the guidelines page. We don't need a portlet tag, because portlet pages are going to be made children of the portlet page (plus their page name already has "portlet" so it should be okay). Also for product, those should be alternative tags to the version number, but if it's just liferay then the version tag will suffice.

Thanks!

[Samuel Liu, geändert vor 13 Jahren.]

Hi all,

Please read the updated Wiki Guidelines, particularly the section called "Wiki Community Cleanup"

Thanks!
Sam

(Hattip to Simon for the tags rules)

[Samuel Liu, geändert vor 13 Jahren.]

Progress Update
-------------
Well, going through all the articles in the wiki is proving to be a longer process than we had originally believed it to be. Out of the 800+ articles we once had, we now have about 700 if not less. A lot of nonsensical articles were deleted (one literally had contents that said "no data" and another one had some jibberish about "the glass half full" with absolutely nothing about Liferay). In addition, many proposal wiki articles were moved to the proposals wiki. Some articles have been renamed -- we still have to rename all the "How to" articles, since those are not good titles, and then we will move them under their respective features/portlets so that people can find them better.

A lot of being done, however. We are making sure that most wiki posts have a table of contents and that the contents are intelligible. We are also doing a good job reorganizing the structure of wiki pages. If you go to certain wiki pages, you will now see on top the parent articles -- eventually we want to make every article have at least one parent. This way, it will be possible to navigate the wiki and to find relevant articles without even using search. Of course, search will still be there for all to use. Right now the main stimulus for the tree-style, parent-child organization is that that digging through a list of results organized by update date isn't ideal. It's what you do when you click "development" in the wiki index though.

We hope to change that in the near future!

Tagging with versions is still vital. We hope that everyone can continue to help us in that, because it is the most important task that people can help us with. Please read the wiki guidelines before offering your help though -- it would be terrible if you tagged "liferay 6.0" instead of "liferay v6.0" and then realized that your work was in vain!

We'll keep everyone posted -- thank you if you've been helping out. There have been some silent helpers in the background

Warm regards,
Sam

[Samuel Liu, geändert vor 13 Jahren.]

Progress Update
--------------------
We've worked through close to 200 articles now, formatting, updating, pending deletion many of them.

We had a long conversation about how to deal with articles of other languages too. We've decided to start a parallel tree of translated articles while our number of translated articles remains small. We hope to have wiki localization eventually so that we can translate our wiki.

Out of the 800+ articles we started out with, there are fewer than 700 left. We've been pruning a lot, merging some articles, and moving many old things to either proposals or pending deletion.

Hopefully the wiki's organization will improve drastically within weeks

We're still working on this and help is greatly welcomed.

Warm regards,
Sam

[Samuel Liu, geändert vor 13 Jahren.]

Progress Update
-----------------
The tree sorting is getting faster. Out of 11 pages worth of printed article titles, we've worked through roughly 3. So about 3/11 of the wiki has been scraped through, deleted or rewritten, recategorized, retagged, and redone. It's been super laborious but we're working hard to continue until 100% of the wiki has been reorganized. Then we're looking to make other changes and to help improve documentation for specific features.

Hope to get a lot done this week.

Warm regards,
Sam

PS Still looking for community support! Please join us!

[Samuel Liu, geändert vor 13 Jahren.]

Progress Update
----------------
Pages with titles from A-G have been taken care of. We're making very good progress and in fact the number of wiki articles we've burned goes to show the amount of clutter. We still have a long way to go -- even within our reorganizations, there are poorly categorized things, but seems like the articles are improving a lot. We are standardizing the articles with a table of contents and proper headings.

Hopefully these documentation improvements will directly help users find information more easily.

We are aware that wiki search isn't the greatest at this point -- we would like to be able to offer a tree-style traversing method so that users can follow logically linked pages to find suitable information.

Warm regards,
Sam

[Scott P, geändert vor 13 Jahren.]

Samuel Liu:

Progress Update
----------------
Pages with titles from A-G have been taken care of. We're making very good progress and in fact the number of wiki articles we've burned goes to show the amount of clutter. We still have a long way to go -- even within our reorganizations, there are poorly categorized things, but seems like the articles are improving a lot. We are standardizing the articles with a table of contents and proper headings.

Hopefully these documentation improvements will directly help users find information more easily.

We are aware that wiki search isn't the greatest at this point -- we would like to be able to offer a tree-style traversing method so that users can follow logically linked pages to find suitable information.

Warm regards,
Sam

Awesome work! Thanks to everyone working on this.

[Sohui Gu, geändert vor 13 Jahren.]

Great work!!
Samuel!!
Really,I wanna join, but I am very busy these days on project, Hope I can help later!!

[Samuel Liu, geändert vor 13 Jahren.]

Yup! All help is welcome