These guidelines have been written to help contributors write better wiki articles that are useful for as many people as possible.
Table of Contents [-]
- Choose a good title
- Always identify the Liferay version through a tag
- Always identify the topic
- Add some tags but not too many
- Do not make the page personal, make contributions easy
- Link to the official documentation as much as possible
- Follow common editorial conventions
- Deletion Policy
- Wiki Community Cleanup
- General Questions
Choose a good title #
Choosing a good title is one of the most important parts of creating a wiki page. A good title will make it easier for people to find out quickly what the page is about and will make it easier for other people to link to that page.
This last part is much more important that it seems at first, because the health of a wiki depends on how many links there are among the articles so that people can browse through all the information easily.
Here are some general recommendations:
- Use nouns instead of verbs
- Good examples: Permission System, Users Administration
- Bad examples: How to use the permission system, creating a wiki page
- Make the title as short as possible
- Don't add the word "Liferay" unless it's really necessary to avoid confusion (since all the wiki is about Liferay anyway)
- Instead of mentioning versions in the article, unless strictly necessary (separating out different methods for accomplishing the same thing on a specific version), tag the article with relevant versions. This way, future readers can add tags based on the article's expanded relevance.
Always identify the Liferay version through a tag#
When you write an article you are probably writing it about an specific Liferay version. Please, identify which version it is for through a version tag. Note that there aren't tags for maintenance versions (when the third number changes), only for major and minor versions. That's because there are not functional changes in maintenance versions.
If the article works with several versions, add tags for all of them. If some instructions are specific to a single version, create a page subsection for those instructions and make clear in its title or introductory text for which version they are valid.
If you read a wiki article that is tagged for a Liferay version that also works in another version feel free to edit it and add the tag for the version you've tested it with.
Always identify the topic #
We have created a set of tags to help identify the topic of every wiki page. These tags are:
- Installation Deployment Setup
- Starting with Liferay
- Using Liferay
- Understanding and Improving Liferay
You should select at least one of these tags (and preferably never more than two) for every page created. These tags have a link from the main wiki page, so adding this tag to your title ensures that the page will have more visibility.
Add some tags but not too many #
Adding tags helps people find related articles even if the original authors didn't know about the related article. Don't add many though, because they will clutter the page.
Also note that the best tags just have one or two words.
Do not make the page personal, make contributions easy #
A wiki is all about many people doing small contributions gradually. If you are creating a new page don't make it very personal because you'll scare away other contributors. Some simple rules to follow are:
- Don't mention your name or company (your name will be stored for you in the history)
- Use the impersonal form. Avoid sentences that start with "I" "I did this...", "I tried that..."
Link to the official documentation as much as possible #
Liferay's official documentation will always contain the most accurate information about Liferay. Try to link to it from your page so that your readers know how to find more information about your specific topic.
At the time of this writing, the official documentation is composed of the Administration Guide which is only available in PDF. When linking to it, link to the page from which it can be downloaded instead of the direct PDF link, so that when more information is added people will notice. Also try to specify the relevant section of the PDF along with the link.
By the time you read this there might be also a developer guide. Also both guides will probably be available in an HTML format where you can link each specific section directly.
Follow common editorial conventions #
You can read the Liferay Editorial Guidelines for a good example.
Deletion Policy #
Articles that lack information may be merged into other pages or deleted. When any content is submitted, it is understood that this is a public arena and that the content may be modified in any way: for correctness, readability, spelling, etc. The article may also be deleted for organizational reasons or if it is unclear and serves no purpose. Spam is actively deleted and will result in a permanent ban.
Wiki Community Cleanup #
When correcting wiki pages, each page should be tagged as follows:
Wiki section tags: to what wiki sections this page belongs to e.g. using liferay, development, installation
Liferay version tags: e.g. liferay v5.2, liferay v6.0
Tags like "liferay 6.0" should be changed to "liferay v6.0" for consistency.
Additional Tags (optional) #
Product tag: liferay ide, alloy ui, social office
Functionality tag: web content, blogs, social equity, forum, permissions, community, organizations, software catalog, polls, wiki, etc.
Related tag: cache, performance, maven, eclipse, svn, tomcat, alfresco, oracle, etc.
General Questions #
Please ask all questions about a wiki post in the Forums. This way, discussion can be brought to a wider audience. Please reserve wiki comments for article suggestions and things like "This article is outdated" or "This article is incorrect." When possible, make changes to the wiki article itself rather than using the comments to ask others to make changes. If you have information to add, please put it in the wiki article body and not in the comments.
To add translations of pages, follow the translation instructions.