Documentation revamp: status and future plans
Company Blogs September 22, 2010 By Jorge Ferrer Staff
As you have probably already noticed we've just made public a quite large revamp of our documentation. This is the result of a project that has taken several months and has involved gathering feedback from many sources of Liferay's ecosystem, writing and improving documentation, improving the existing docs and developing tools to make them more easily available.
But we don't want to stop here
The purpose of this post is to review the current status of the docs and the plans that we have to keep improving them. Some of them will not be possible without the help of the community so I hope you can see this as an opportunity to contribute :)
Official documentation: www.liferay.com/documentation
This is the main source of accurate information about Liferay. Previously we only had one official guide (Liferay Administrator's Guide) which was only available in PDF or printed and we realized that some people didn't find it. We've expanded this with a Developer's guide and have made it available online so that it's much easier to find, search and link. We have created sections in the site for the last 3 stable versions: 5.1, 5.2 and 5.3. Each of the versions have the following sections:
- Getting started: this is mainly to add links to specific sections of the Administrator's guide and Developer's guide that we think will be useful for people getting started with Liferay.
- Future plans: We may add more links based on feedback from people. But we want to keep the number small since otherwise it would loose its purpose.
- Administrator's guide: this is a very thorough guide that covers the installation of Liferay for all supported applications servers, including cluster setups. It also covers user's guide for the usage and administration of the web content management and the collaboration suite.
- Future plans: With each edition of the guide Rich plans to add new chapters for the different suites included out of the box with Liferay.
- Developer's guide: Since Liferay is a pretty large development platform developing for it offers a very wide set of options. Because of that the hardest part is getting started, finding out what the main options are and when should each be used. This guide provides a general overview of the main strategies to extend Liferay and gives advice to choose which one to use in each situation: Portlets, Themes, Hook plugins, ext plugins, etc.
- Future plans: We want the guide to be short enough to allow people to read it entirely (or almost) before starting any Liferay development, but still provide enough information to get started. I think the main goal should be to keep finetuning it so that it lowers the barrier of entry for newer developers. We are also considering adding some additional sections, such as one about the creation of web content templates with velocity or XSL.
- Additional resources: This is an area were we want to link to any additional resources that will be useful to users. It will include links to specially significant wiki articles and blog entries, links to videos about that version of Liferay and links to books about Liferay.
- Future plans: we are currently working in this section for Liferay 6. It should be ready soon. Later, we will continue adding resources that we find particularly interesting.
Official books and third party books
We now have two official books that cover Liferay:
- Liferay Administrator's Guide: This is an open source book that we've made available online and can also be bought online through Lulu as a way to help fund it's continued development.
- Liferay in Action: This book will be published by Manning and offers a very complete trip through Liferay as a development platform. It's an excellent continuation if you've read the developer's guide and want to learn more. It's already available through Mannings Early Access Program (MEAP). In fact you can find some banners in the documentation section to get it with a 35% discount, courtesy of Manning to our community.
There are also two other books written by third parties that add to Liferay's documentation. There are at least two that I know of:
- Liferay Portal Enterprise Intranets, by Jonas Yuan, an active community member. Publshed by Pakt.
- Practical Liferay, by Poornachandra Sarang. Published by Apress.
Community wiki: wiki.liferay.com
The wiki is the place where everybody can contribute to the documentation. It currently has more than 900 articles which speaks for the number of contributors around. The drawback of having so many contributors is that the quality of these articles varies a lot, and some times they become outdated which is not easy to notice as a reader except the hard way (when the instructions fail). We had noticed that some people thought the wiki was the official documentation and this made it even more frustrating. To avoid that confusion we've moved the wiki to the documentation section, hoping that the menu makes it clear that there is more documentation available. We have of course kept a link in the community section.
Sam Liu, with the help of several community members, has spent the summer reviewing a very large amount of articles fixing all issues they found and helping organize them better. As part of this effort we also wrote an article with the Wiki Guidelines.
Future plans: There are many things to do to get the wiki into shape and make it easier for everybody to contribute. First of all we want to encourage the usage of the wiki as an Encyclopedia. That is, most of the articles should be titled after specific components of Liferay. Because of that a good place to start looking at a place to add information is this page: www.liferay.com/community/wiki/-/wiki/Main/Portlets
We also want to start adding more and more links from wiki articles to specific sections of the administration guide and developers guide. That will help readers find the "official" instructions. It will also help focus the efforts of the wiki volunteers into extending the official documentation, rather than duplicating it. This is a lot of work so we really appreciate your help here. If you find a wiki article that provides some information that either extends or even duplicates that offered by the official documentation, please add a link to it at the top of the article so that it's easier to find for future readers.
Javadocs & other reference documentation
I almost forgot this one. One of the ongoing efforts that I'm pretty sure many people will be happy about is the work we are doing to greatly improve the information included in our Javadocs. One common complain from our community is that our Javadocs don't contain much information (actually most of the time it doesn't contain any). That was because our policy was that Javadocs weren't allowed. One of the reasons was that several of us had had horrible experiences with APIs whose Javadocs were often outdated and inconsistent which was worse than having no Javadocs at all. Also since the Liferay code is available we often end up using it directly. But we do understand that Javadocs are necessary for many developers. Because of that a few months ago we defined a process and started an effort to provide Javadocs with a quality that we all feel comfortable with. As a result, Connor (who is leading this effort) has written a set of JavaDoc Guidelines that will let every developer know how Javadocs should be in Liferay.
What's the current status? We've added quality Javadocs to around 50-100 classes already (mainly utility classes and some services) and the number is increasing weekly. We are currently starting to work in package.html documentation and are discussing how we can extract out the implementation classes from the javadocs so that it's easier to find what can really be used from plugins. We'll keep you up to date.
That's it, I hope you enjoy the new documentation. If you'd like to help improving it further or let us know your suggestions, you can use a new category in the forums created explicitly to discuss about documentation.