This year, the Knowledge Management team at Liferay set out not only to document Liferay 7/DXP, but to document it well. To do this, we identified several improvements we wanted to make:

• We wanted to connect powerfully with users and customers. To do this, we made a significant effort toward documenting the right things, the things people needed the most to learn about. We also did what we could to promote the documentation, through our @Liferaydocs twitter account, being active on the forums, and responding to feedback.
• We worked to improve the quality of the docs. We divided ourselves up according to Engineering’s functional teams. We worked closely with developers to produce docs not from the perspective of outsiders trying to figure out the product, but from the inside, describing how the product is designed to work, putting the most important features front and center.
• We collaborated cross-functionally with other groups like Liferay’s Support team. This helped us improve the docs by identifying and answering the questions users and customers asked us about.
• Finally, we looked for ways to broaden our communication services and skills. Realizing we have someone trained in CGI, a musician, and a voice-over artist on the team, we started enhancing several tutorials with videos. Look for more of these in the future.

But it wasn’t enough to try all these things, pat ourselves on the back, and say we took Liferay’s documentation to the next level. We care deeply about Liferay developers and their experience with the platform. The only way to really know if we were succeeding was to ask. So we took to Liferay’s Twitter, community chat, and internal systems and asked a whole bunch of questions to help us determine the state of the docs.

Here’s what we learned.

Survey Population

Part of the survey asked about the people filling it out: how long have you worked with Liferay; how often do you code on Liferay’s platform, etc. We wanted to know who we were reaching and what their needs are.

First, the experience level: how long have responders been working with Liferay’s development platform?

The majority of responders are experienced developers. More than half have worked with Liferay’s platform for 5 or more years. Interestingly, though, we have almost as many developers new to the platform as have been working with it for a long time.

Next question: how often have you used Liferay’s documentation?

About two thirds say they use the documentation regularly. This means we have well-informed responders who have regularly searched for and used Liferay’s documentation. Only six said they rarely used the documentation.

Next question: how often do you code on Liferay’s platform?

Again, the majority of responders regularly write code for Liferay’s development platform. This is good: it means most responders refer to the documentation on a regular basis.

Next, we wanted to find out how many people from Liferay responded versus customers and those from the open source community.

We were hoping for more of an equal distribution between developers employed by Liferay and those from the community, so this gives us our first take-away from the survey: how can we better get feedback from the community and our customers? Clearly, the way we went about it didn’t work well.

Reference Docs

There were several questions that examined Liferay’s reference documentation. Let’s dive into those responses.

First, we wanted to ascertain if people were using the reference documentation.

Developers are equally divided between Hourly/Daily/Weekly and Occasionally/Never. We’ll get to why next.

We then asked if developers could find what they wanted in the reference documentation.

Overwhelmingly, developers were either neutral or disagreed with this statement. The plain fact is that Liferay has struggled to document our APIs satisfactorily. While we have made great strides, more needs to be done.

To fix this, we’ve initiated a new process that should streamline Javadoc creation for developers. We’ll follow this closely to make the best impact on our API docs as possible.

Related to this is the experience of finding the API docs, so we asked about that too.

Here, we are doing slightly better. Over the past year, we made an effort to style our API docs to make them easier to read than what’s generated by default. We still have a lot of work to do, however: our presentation on docs.liferay.com is still a default Apache file system browser. We plan to launch a project in 2018 to fix this.

We do invite the community to help with the docs if you’re so inclined. Does anybody know about this? Let’s find out.

This clearly indicates that people are not familiar with the process for submitting Javadocs. We’ve modified the guidelines in our GitHub repository accordingly; please check our repo any time you have a question about the Liferay documentation process. Please also feel free to submit feedback on LDN or on Liferay’s community forums.

We asked other questions about the rules for submitting, but since most people weren’t familiar with how to submit Javadocs, those results aren’t surprising.

The most reasonable interpretation of this is that since most weren’t familiar with how to submit Javadocs, most were neutral on whether there are a lot of rules.

Let’s move on to another section of the survey: how well people can navigate the docs.

Navigation

Some of the most interesting feedback came from the question we asked about navigating the docs.

Less than a quarter of developers agreed with this statement. The number one takeaway from the survey seems to be this: when developers look for docs on a particular subject, it’s hard to find them.

We have big plans for LDN in 2018: integrating it with community.liferay.com and upgrading it to 7.1, along with an entirely new user experience. This includes taking steps to make the docs easier to find and easier to navigate.

Next, we examined whether we had the right format for the docs.

Format

When we first launched LDN, we knew we had two different audiences for docs: newcomers who need a longer, step-by-step series of tutorials to help them get off the ground, and veterans who understand the framework and need short, focused tutorials that cover what they’re working on at the moment. We dubbed the first type of documentation Learning Paths to evoke their longer experience as a journey down a path to Liferay enlightenment. We dubbed the second type as Tutorials to highlight their standalone nature.

We wanted to know if this was working. Do people like the longer Learning Paths, or would they prefer shorter, more focused Tutorials?

Far and away, developers like both. This makes sense: all of us were beginners once, and those longer “from zero to application” Learning Paths are extremely helpful when you don’t even know what you don’t know. Similarly, once developers have their feet under them, they want something quick to refer to, and Tutorials are good for that.

Next, we asked about the format. We’ve gone to web-only documentation for 7.0; was that the right decision, or did developers like the physical books, ebooks, and PDFs we created in the past?

We asked responders to rank the three formats in order of priority. Clearly, the web is the winner here as the number one priority, with ebook/PDF coming in second, and physical book coming in third.

Our final set of questions focused on the docs’ content. This was the core of the survey and the data we wanted the most.

Content

Our questions about the content focused on the quality of the docs: are they relevant; are they detailed enough; do they help people learn? Where they fail, are we headed in the right direction on improving them?

We really wanted to know these things, because we want the docs to serve users and developers well.

The first question asked whether the docs help users learn new concepts.

We were very glad to hear that the vast majority of developers learned new concepts from the docs always/regularly/sometimes. Only 8 developers said rarely or never.

It always helps, however, to ask for the same information in a slightly different way, so we also asked if readers found the answers to questions they had about Liferay from the docs.

We had a similar, but slightly less rosy result. Clearly the always/regularly/sometimes has the majority, but the always and regularly people are fewer than the sometimes people, and we have a larger group who says rarely/never (almost a third). It’s clear that we must do more to learn what developers are struggling with and get those questions answered.

One of the things we want to do more in 2018 is to be more active on the forums, learning what people are struggling with, and then documenting those things. We are also working more closely with our Support team and filling out those areas in the docs where we find customers struggle.

We weren’t done asking about this, though. Next, we had some questions on the level of detail in the docs.

Here, the always/regularly and the rarely/never groups take a little more than half, while the sometimes group is the largest. This was one of the items we tried to address this year by working more closely with Liferay’s developers. Using their knowledge, we dived more deeply into the various development topics. These results show us we made some headway, but we must do more.

We next asked about whether what is documented is relevant to readers’ needs.

Here, the agree/strongly agrees win out, with only a small fraction disagreeing. For the most part, we’re documenting the right things; the things people need to know to get their work done.

Beyond the content, we also wanted to know if we were communicating well. To find out, we asked if the documentation’s writing style is easy to understand and follow.

Almost three-quarters of responders said they agreed or strongly agreed that the docs have a writing style that’s easy to understand and follow. We work very hard on this. I will have a blog entry later on our process, but it’s a multi-step process that’s designed to produce clean and clear prose that’s easy to understand, for both native English speakers and non-native English speakers.

Finally, we wanted to find out about how the documentation trends: is it getting better over time?

Overwhelmingly, the response is yes, the docs are improving. That’s really great to hear, but we know we still have many areas of improvement. We will endeavor to make this improvement trend continue.

Well, that’s the survey. Let me sum up the takeaways here at the end, because they will inform our goals for 2018:

• We must find better ways of garnering feedback from outside Liferay.
• We must increase coverage of Liferay’s API documentation (Javadoc, Taglib doc, JSdoc).
• We must make the presentation of the API docs better. Our redesign of LDN must focus on making the docs easier to navigate.
• We must be more active on the forums, community chat, and anywhere else to learn about what developers struggle with, so we can document the right things.
• We want to document the right things with a deeper level of detail.

Thank you to everyone who filled out the survey this year! We will check back next year with another survey to see if we’re able to improve on all these items in 2018.

At Liferay's North American Symposium, I announced the immediate availability of a new website we've developed specifically for those who use Liferay and write code on its platform. We call this site the Liferay Developer Network.

This site is the new home for Liferay's documentation and, by the time it gets out of beta, Liferay's community pages. After receiving good feedback from our user community for years, we knew that the way we currently publish our documentation had some problems:

1. Many times, people would search either on liferay.com or the search engine of their choice, for a topic they needed to know about. Often, the search results would direct them to an article in Liferay's Wiki. The Wiki over the years has become a place where well-intentioned Liferay employees and community members have placed articles describing how to use various features of Liferay. Because the Wiki has been on the site for so long, Google tends to rank its articles pretty high. Even though I've been shouting from the highest turrets that the Wiki is not Liferay's documentation, Google's indexing bot doesn't have ears.

   Unfortunately, however, the Wiki is also where user documentation goes to die. Articles are written and then abandoned by their authors. They then become out of date and actually do more harm than good, by sending people who read them down rabbit trails that were meant for older versions of Liferay. For this reason, we are retiring the Liferay Wiki. In its place, we've created Liferaypedia, a new Wiki for defining Liferay, development, and open source terms.

2. We've also heard feedback that our current documentation pages are hard to navigate. There's a reason for this: they're just HTML versions of documentation that's organized as books. We've now changed that. The Liferay Developer Network is divided into four sections:

   • Discover: The contents of Liferay's user-oriented documentation have been re-imagined for this section. Front and center is the documentation for Liferay Portal. Using a new interface, it's much easier to find the documentation you're looking for. The Social Office section contains our Social Office documentation. The Deployment section is for Liferay systems administrators everywhere: it contains documentation for installing and configuring Liferay, including clustering.

   • Develop: This is the section for developers. When we designed it, we asked ourselves, Who is our audience, and how will they want to learn about Liferay?. What we learned was that we have a variety of readers: some want to learn in a step-by-step fashion, and some already have a project and want a quick answer to a question. To serve everybody, we created learning paths for developers new to Liferay who want to start from scratch, and we created tutorials for developers in the midst of a project who want to learn something quickly. And, of course, we have our reference documentation so you can look up APIs, tag libraries, DTDs, faces docs, and properties docs.

   • Distribute: Everything developers need to know about distributing their applications on Liferay Marketplace is right here. You can learn all about the benefits of Marketplace, how to get started, view the Marketplace User Guide, and more.

   • Participate: This is the new home for Liferay's community. As the months go by, we'll be migrating more and more of our community pages here. Currently, it contains information on how to contribute to Liferay, the aforementioned Liferaypedia, the feature ideas page, and the feedback forums.

3. Want to contribute to the documentation like you maybe once did with the Wiki? We haven't left you out. In fact, we welcome contributions to our documentation. And here's the real kicker: because we have a team of people reviewing and updating our documentation, you can do the same thing you did with the Wiki. Submit it and forget about it. We'll take care of keeping the documentation you submit up to date with all the changes that happen to Liferay in the future. You won't have to worry or feel guilty about your submitted documentation again! Instead, you can feel good knowing that you made an important contribution to Liferay, because contributions help our community. There are three ways in which you can contribute:

   • Editing existing documentation. Every piece of documentation on the site contains an Edit with Github button. This lets you go to our documentation repository and use Github's tools to edit documentation right in your browser. When you're finished, you can send a pull request to the liferay-docs repository, and we'll review your updates and push them into the site.

   • Creating new documentation. Every section of the Liferay Developer Network has a corresponding folder in our repository. In that folder is another folder called new-articles. If you have documentation for a feature we don't currently cover, you can submit it right into this folder. You don't have to know where it goes in the rest of our docs or anything like that. We even have a shell script (Mac, Linux) and a batch file (Windows) that lets you preview your Markdown in HTML before you submit it. Submit it to the liferay-docs repository.

   • Contributing to Liferaypedia. We still have a Wiki, but it's for defining Liferay and open source terms. Currently, it's pretty bare, and we need to fill it out. We could use definitions for all kinds of terms that are germane to Liferay, like CMIS and SAML, as well as Liferay concepts like Theme Display and Service Builder.

In closing, I just want to say that we've designed this site for our community of users and developers. All design decisions were made based on feedback from our community. We know we're not perfect, however, and we may not have captured everything you've been telling us over the years. For that reason, and because we're in beta and can still change things, there's a feedback link at the bottom of every page. We welcome your feedback. Don't know where to start? How about starting with our learning paths. This is a brand new effort we're making, the learning paths aren't complete yet, and we want to make sure we're getting it right. Try reading the first learning path and let us know what you think. Will it help beginners get started with Liferay?

Or maybe you're more interested in mobile development on Liferay. We have a whole set of mobile tutorials that you could read and let us know if they're hitting the mark on Liferay mobile development.

Thanks for reading this long post, and thanks for all the great feedback we've heard on our documentation over the years. We hope that the new Liferay Developer Network serves you well as we continue to build it.

I am pleased to announce the immediate availability of the print edition of Using Liferay Portal 6.1! For those of you on your toes (and you know who you are), it's actually been available since Friday, but who reads a blog entry that is published on Friday afternoon?

It's a big book. We're getting close to 700 pages now in print, and that does not include the properties reference, which we think is better as an online reference than stuffed into the book (plus, we can lower the price if we excise those pages). I want to acknowledge the hard work of Liferay's Knowledge Management team for a job well done: Jim Hinkey, Stephen Kostas, Jesse Rao, and Cody Hoag. In addition to these guys, some other key contributors include James Falkner, Bruno Farache, Michael Han, Jeffrey Handa, Mark Healy, and Jonathon Omahen.

So if you like big, thick books on your shelf, especially ones with the Liferay logo on them, why not pick one up?

Of course, we're not stopping there. I'm in the midst of working on the styling of the epub version of the book, which we'll release next. Stay tuned!

One of the benefits of moving our documentation out of LibreOffice and into Markdown is that Markdown converts to many publishable formats. We're already converting it into Liferay web content for display on the web site. I had always planned to publish also in PDF and print format, and up until recently, I intended to use the open source DTP program Scribus to do so. Those of you who attended the talk that Jim Hinkey and I did at the NA Symposium know this, as it was actually a part of the slides.

I spent some time attempting to create the book layout in Scribus. While Scribus is a great program, it has limitations with our workflow, some of which are not Scribus's fault, and some of which are. The biggest issue I had was that none of the images would import into Scribus with the text. I had to do them all manually and re-add all the captions. I spent about two or three weeks doing this.

Suffice it to say that I soon realized I needed to find another tool, or I'd probably be finishing the book layout sometime this summer. The conversion tool we use for our Markdown--Pandoc--also supports LaTeX, a type-setting tool that's been around for a long time, and something that Darren, a college professor friend of mine I haven't seen in many years, tried to get me into, oh, about 15 or so years ago. I've avoided it all these years in favor of various systems that gave me a WYSIWYG view into my documents.

Well, in this case, LaTeX saved the day, and I haven't seen Darren in so long that maybe he won't even have the  opportunity to say "I told you so."

The conversion to LaTeX preserved all the images, along with their captions. Combined with xelatex, the Memoir class, and lots of hand-massaging of the file (which we'll automate next time), we now have a PDF, almost suitable for
publishing, and which we've made available as a download on the Documentation page. It just needs an index at this point, which is something we're working on.

Next up: print, epub, and Kindle formats. Stay tuned!

Since we haven't been announcing it much, you're probably unaware that we've recently started making weekly updates to the Liferay documentation. This is one of the reasons we haven't published the PDF or the book yet, though now we're
getting much closer to doing just that.

But I want to use this space to point out what's been updated recently, so you can see all the great new content we've been working so hard on. And after this, I'll be writing a weekly blog entry describing everything that's gone in that week. This is much easier than following Github commits, and it gives us the opportunity to hear what's most important to you. That, in turn, helps us to define the priorities for any upcoming documentation.

But first, I need to play catch up. To do that, I'm going to steal a couple of graphics that I'm planning to present with Jim Hinkey at Liferay's North American Symposium next week. Because of the relative size of the graphics, one resized better than the other. Regardless of that, it shows just how much of the new User Guide and Developer Guide is new material that we've added for the 6.1 release.

First, the User Guide:

Next, the Developer Guide:

Finally, here's what we added this week:

- New JBoss 5.1 installation instructions

- New chapter on OpenSocial (see Cody Hoag's blog entry)

- New section on using the Android and iOS Liferay Sync clients

- Best practices for Struts Action Hooks

As always, comments are welcome, and thanks for reading!
 

One of the things we've been working on over the past few months is a complete reorganization of Using Liferay Portal, the documentation for our flagship product, Liferay Portal.

For the 6.1 release cycle, we decided to rename the book (it used to be called the Liferay Portal Administrator's Guide) so that it would better reflect its content. For several releases, the "Admin Guide" (as we'd call it for short) had been more than a guide for Liferay administrators: it also contained a growing library of end user documentation on Liferay Portal's functionality. So for 6.1, we renamed it so that its title would match what was actually inside the book.

After a month or two, though, we realized that this was not enough. To truly be a complete user's guide, the book's content needed to be reorganized. Working with Liferay's Product Management and Engineering groups, we spent a couple of months moving, reorganizing, changing, and wordsmithing the text. To do this, we first created an outline of what our "ideal" user's guide would look like. We then moved our existing content around to match the outline. Finally, we went through all the text and smoothed everything out.

The result is what you see on Liferay's documentation page. But we aren't done yet.

When re-outlining the content for the book, we realized that some features were missing. Our next task, then, is to fill those gaps. Once we've done that, we'll be ready to publish the book in other formats, such as print, PDF, and EPUB.

I want to thank all of those who worked so hard on this reorganization: Jesse Rao, Mark Healy, and Jim Hinkey, as well as Ed Chung and Jorge Ferrer for their guidance. Though we're all Liferay employees, I hope you know that community members are welcome to participate. Not everybody is a developer. If you love Liferay and you like to write, you are more than welcome to help us. Head on over to github.com/liferay/liferay-docs to grab the source files for our documentation. Here are some gaps that we need to fill:

• Chapter 10: need content for workflow in applications such as WCM, Docs & Media, and collaboration.
• Chapter 12: we need to cover some of the smaller applications, such as Bookmarks, Shopping, and Weather.
• Chapter 15: needs real world examples of using Liferay's security model, as well as best practices.

I hope you enjoy the new book. I know it's not perfect, so any comments, questions, and suggestions are welcome. Thanks for reading!

Writing is something I've been doing for a long time. I mean, a long time--since I was something like 12 years old. To give you a piece of perspective on this (without giving away my age), I was 12 years old in the 1980s. Since then, a lot of things have changed with regard to writing: word usage (I still by default write *worshipped* and *kidnapped*), the process (mindmapping replaces outlining for me), and most especially the tools (pen/pencil and paper, to typewriter, to text-based computer, to graphical computer).

Since the Liferay documentation team has recently undergone a lot of changes with regard to the way we write documentation, I thought it might be cool to start a blog series on what we've done and the philosophy behind why we've done it, with some personal reflections along the way. I hope you find this interesting. If not, feel free to stop reading and move on to some of the other excellent bloggers here on liferay.com. Much of what follows in this first part is somewhat of a response to a blog entry I saw here: http://www.guardian.co.uk/books/2011/nov/03/creative-writing-better-pen-longhand.

I was bad at penmanship in grammar school. It was the only subject in which I got Cs and Ds consistently. I struggled through capital letters, chafed through lower case letters, and dragged on cursive. Finally, in the 5th grade, when penmanship was no longer a course, I switched myself to writing in all caps, and have stuck with that from then until now. Why? Because I'd been writing in all caps the longest, and the nature of capital letters means you have to slow down and be more careful, thus producing more legible text. And by the 5th grade, none of my teachers cared or said anything about it.

In 6th grade, we started getting these spelling assignments where you'd have a list of new words to spell, and you had to make up sentences in which the word was used. Rather than produce a bunch of dry, boring sentences (e.g., The patient was paralyzed from the waist down.), I'd make up stories and work the spelling words into these. My teachers loved it. I always got an A+ on my spelling sentences--when my teachers could read them.

Somewhere around this time, I got a plastic "children's" typewriter. I think it was only labeled a children's typewriter because it was cheap plastic: it did have metal hammers and a real ribbon. My mom, who is an office manager for an orthopedic surgeon, was always an excellent touch-typist, and she began teaching me to type. At this point in my life, though, I didn't have much use for the skill, because I couldn't use it much for my school work, and I hadn't gotten the idea yet that I might someday become a writer. Handwriting was everything in school work at this time, and I sucked at it.

Also about this time, rather than typewriters, friends whose families had more money than mine began getting Commodore 64 and Apple II computers. I was incredibly interested in these things, but they were way out of reach for me. I remember the envy I felt in 8th grade when we had these bulletin board projects to do and my friends were able to produce posters and banners strung together on dot-matrix paper, while I was stuck with crappy construction paper and markers.

I don't remember what circumstances brought this about--it was probably getting older and having to start writing papers for school--but in the 7th or 8th grade, my stepfather pulled out for me this old Royal manual typewriter. The thing must've weighed 50 pounds. We lived on the 2nd floor of a two-floor duplex, and I'm sure if I ever dropped it, it would've gone right through the floor and hit our neighbor on the head. It was gun metal gray and had round keys that when you pressed them, went way, way down, slapping a hammer onto a page. At the end of each line a bell would ring, signifying that you needed to finish the word you were working on or hyphenate it. Once you did this, you'd reach up with your left hand and in a smooth motion that my mother demonstrated for me, use a bright, chrome lever to swipe the "platen," or the roller the paper was on, back over to the right to begin a new line. I looked at the machine in awe. Everything about it said to me, "serious writing."  

Coincidentally, sometime before this typewriter appeared, I'd done some of my first bit of creative writing outside of my spelling sentences, just for fun. I'd written a short story that had been inspired by a dream I'd had, and I'd also attempted a magazine based on Mad Magazine which I called Crazy Magazine. Of course, my drawing skills are probably worse than my penmanship skills, so the magazine really had no prayer of going anywhere--but I do remember photocopying it for some friends and handing them out.

The story, though, had some promise, if other people could read it. So I thought maybe I could try my hand at another one--this time, on the typewriter. I was in high school now, and taking a typing class, so if it didn't work out, at least I'd become a faster typist. And so I produced a story called The Deadly System, also loosely based on a dream I'd had (I was having all kinds of weird science-fiction dreams at the time). I stuck this one in a green folder and gave it to a friend of mine--an artist--to read. The story inspired him enough to illustrate the front of the green folder with the main protagonist of the story, which I thought was pretty cool. There are more details here, but they aren't germane to my point.

I was off and running. That story blossomed into several more, and soon I began thinking that I might want to do this writing thing for a living. Upon my high school graduation, I got a PC--a discounted Philips 8088 with a monochrome screen--to take to college with me, where I would be majoring in English. The 386 had just come out, so this machine was already antiquated, but I loved the thing. I did all of my college writing on that PC, in WordStar, where I most appreciated being able to continuously type without have to reach up and swing that platen over at the end of every line. And of course, there was the all-important Backspace key. Right before my senior year, I purchased a 486, and of course I did my writing on that. I have more to say on this subject, but that will have to wait till part two.

The point I want to make here is that for me, the keyboard has always represented serious writing--whether that writing is creative, scholarly, or technical. Writing with a pen always got in my way, and represented extra, tedious work--in other words, re-typing, not to mention deciphering what I wrote--and I thought there were better ways to use my time. I'm happy to write notes in a journal and jot lists, but if I want to do any serious writing, I always sit down at a keyboard. All keyboards are on PCs now, and I definitely have specific thoughts on how best to write on a PC, but they'll have to wait till part two.

If you made it this far, you must have some interest in writing, or in the process of writing. I'd love to hear your thoughts in the comments.

I've learned a lot while writing Liferay in Action. I'm going through my final edits now before the book goes through its production cycle, tightening up the prose and making sure everything is as clear as I can make it. Once of the things I've had a lot of fun doing is the crutch.

What is a crutch? It's a technique whereby you introduce a concept with an anecdote, a story, or an analogy of some kind that speaks to the topic you're about to discuss. It's supposed to draw the reader in and get him or her interested.

You may not know that though I work for Liferay and have done software development for many years, my degree is not in Computer Science: it's in English. So I like to write. My favorite kind of writing is of the creative sort, and I don't get to do it often. So with Liferay in Action, the concept of a crutch was something that I kind of got really into doing. In fact, you might say that I tended to get carried away with it.

Below is an example of a crutch that I had to cut out of the book. It was intended to introduce the concept of Ext plugins, but instead it took on a life of its own and tended to be a bit distracting. If it were to stand on its own, I would give it the title below. And if you'd like, let me know in the comments if you think this would have worked or if indeed it is distracting.

Enjoy!

The Chocolate Monster

Once upon a time, a man woke up after having a strange dream. In that dream, he found himself face to face with a being he couldn't identify, who was glowing with an odd, brown-mixed-with-gold hue. The being's face was obscured, and its body consisted of an amorphous, flowing robe that hid its actual shape. Before he could react to the presence of such a unique person, the being spoke.

“I am not long for this existence. Before I pass into whatever comes next, I must bequeath my unique ability to someone else. I have chosen you.”

“Uh—wow. Um, thank you,” the man said. “Who are you?”

“Who I am does not matter. What I am giving you does. Use it wisely. Use it well,” stated the being, dramatically.

With that, the man found himself enveloped in a bear hug. That odd brownish-goldish glow surrounded him, and he could smell something—something familiar, but for some reason in the dream, he couldn't figure out what it was. The being squeezed harder and harder, until the man began to have trouble breathing. He tried to choke, “Stop!” but to no avail. As the final breaths of air escaped his mouth, he panicked and started to squirm. The smell—whatever it was—was overpowering. How could he smell when he couldn't breathe? He wasn't sure, but black spots appeared before his eyes, and he knew he was about to pass out due to a lack of oxygen. Gasping violently, he screamed, and—

He woke up. And now he could identify the smell: chocolate. Weird.

The rest of the day proceeded normally, until the man came home from work. Living alone, he was accustomed to keeping pretty much whatever schedule he wanted, so it was rather late when he got back. His stomach growled as he stood in his kitchen pondering what to make himself for dinner, and it occurred him that it might be nice to have a snack. He'd been thinking about that dream all day—and also the smell of chocolate. Boy, it would be nice to have a piece of chocolate right now.

Wait, what was that? He opened his right hand, and inside was a piece of chocolate. How did that get there? He smelled it. Yup, it was definitely chocolate. Gingerly, he bit into it. Tasted like chocolate too. So he ate it.

Of course, once you've had one small piece of chocolate, you sort of want another one, don't you? The man did. Before he could reach for the handle of his refrigerator to find some, however, there was another piece of chocolate in his hand.

“Wha—?” escaped the man's mouth. He put the piece of chocolate down on the counter and stared at it, his heart pounding. What was going on here? He placed his hand out, palm up.

“Okay, let's try something,” he said out loud, though nobody else was in the room. He closed his eyes and thought to himself, I want a piece of chocolate! He opened his eyes. There was a piece of chocolate in his hand.

“No way!” he shouted, again, to nobody in particular. Over the course of the night, he found that he could make any kind of chocolate he wanted. He could make dark chocolate. He could make milk chocolate. He could make liquid chocolate. He could make it in any shape, size, or consistency he wanted.

He was a super hero! Well, not really.

He started making chocolate for his friends—any kind they wanted, as much as they wanted. He made chocolate for his town. He made things out of chocolate that really shouldn't be made out of chocolate—like buildings, statues, and even monuments. He became rich by selling his chocolate. Children loved him. Women adored him. Candy companies despised him.

He married, divorced, and married again. Why? Because his wives initially loved the chocolate and the power and the money—but not him. He wasn't the same man he'd been before he had his chocolate power: when you really got to know him, the man he'd become really wasn't all that lovable. For instance, over the years he grew rather fat as he consumed a lot of his own chocolate, but he wasn't a nice fat, or a jolly fat. Instead, he was a mean fat, unkempt, and unwashed. He was also rather selfish—if he wanted something, he could generally get it through his chocolate power. And he did. When someone he knew needed something, he could give it to them if it could be obtained through chocolate, because that was easy. If it took more work than that, well, he had more important things to do. What was most important was that he was famous as the only man in the world who could make chocolate from nothing.

At least, he thought it was nothing. He started noticing the symptoms after he made his first mountain of pure chocolate, up in the Pocono mountains in Pennsylvania. He started to think that maybe his skin had taken on somewhat of a more golden hue. Over the years it got darker and darker, until his facial features were obscured. He became a recluse, rarely seen. He wore dark, hooded robes so that no one could see the change in him. It seemed that the more chocolate he made, the more he changed, and the weaker he became. It was as though using his power drained his life force prematurely somehow. But still he made chocolate.

His greatest achievement, to his mind, was made during this period of his life. He made a chocolate island, floating in the Pacific Ocean. It was his own world, one which could be used and replenished at his every whim. At first he thought this would gain him praise from the world, but instead he received only criticism. As the mountains of chocolate he'd made elsewhere had begun to melt, the surrounding environment suffered. Birds, toads, rabbits, and other animals became mired in sticky goo as the chocolate melted and flowed down. Streams and rivers were choked with pieces of chocolate. If that was happening with the mountains, what could happen with the island?

His skin went from dark gold to dark brown, the color of chocolate. Then it began to glow in that familiar brownish-goldish hue that he remembered from his dream, and he somehow knew that this signaled the end of his life. It had only been ten years since he'd been given his gift. He sat, in a chocolate castle he'd built for himself, alone on his chocolate island, and pondered the meaning of it all. Why wasn't he happy? Why did people shun him? What could he have changed? He fell asleep.

In his dream, he felt an urgency. He had to give away his power to someone else in the dream—because this wasn't a dream, really. He was being given a glimpse into another dimension, another universe, where other people lived. He zeroed in on one house, in a particular neighborhood, and found the person living there. He didn't have time for niceties; he had to do this quickly.

“I am not long for this existence,” he said to the person. “Before I pass into whatever comes next, I must bequeath my unique ability to someone else. I have chosen you.”

The other person sputtered something, but the man had no time to talk. He had to do this now, before it was too late. He could only give the person one sentence of advice, so it had to be a good one—a better one than he'd been given.

“I am giving you a great power—use it responsibly, and for the good of others.”

With that, he embraced the other person as hard as he could, feeling his power flowing from him into the other person.

The man died in his sleep. The other person woke up. That person is you. The power, however, is not necessarily based on chocolate.

When given a great power, it's wise to consider how best to use it. Can it be used for everything? Probably not, and if you try, you'll almost certainly make a mess. Can it be abused? Definitely. Can it be used for good, and optimally, so that it provides the best benefit for the most people? Absolutely, but that will take a lot of thought to accomplish.

Ext plugins are like this. When I first started working with Liferay, we didn't have all these great plugin types you've already seen. Instead, everything, and I mean everything, had to be done using the Extension environment, or Ext environment for short. Ext plugins, as they are now called, give you unlimited power within Liferay to do whatever you want. You could implement your entire site using only a single Ext plugin if you wanted to. But that is not the best way. In fact, more likely than not, if you do it that way, you'll make a big mess. So Ext plugins need to be used responsibly. We're going to look at two ways you can use Ext plugins responsibly:

1. Customizing Struts actions of internal Liferay portlets

2. Modifying core Liferay behavior that can't be done with hooks

For the first use case, I'll be able to show you an example. For the second, since there is so much core functionality within Liferay, what I'll do is list some common things people do with Ext. Then I’ll give you an overview of Liferay's architecture by tracing exactly what Liferay does from receiving a browser request to rendering a page. Since I can't be sure what exactly you may be wanting to modify, this should hit a lot of internal Liferay code, giving you the tools to determine your strategy for making Liferay do what you want.

Once we've looked at Liferay's architecture, we'll discuss some best practices for Liferay development, to help you decide when to use each plugin type. We'll round out this discussion by helping you decide if your changes would be something you could even give back to the product as open source!

So without further ado, let's jump right into Ext plugins.

[end of crutch, rest of chapter begins]

The Liferay in Action MEAP update came out on Christmas Eve, so I wanted to make sure that I let everyone knew about it in case you, like me, have been offline for the past few days. So Merry Christmas from me, Liferay and Manning: you get a whopping big chapter which covers a lot of ground: 

This has been a long time coming, and could not have been done without the help of a whole team of people, but we have finally done a redesign of the documentation pages on this site.

Our previous docs page was, I'll admit, confusing. In fact, we've heard several times that people thought the only documentation we had is in our wiki, and that is far from the truth. The wiki is great, but it's not where we place our documentation. The best place to find official documentation that is vetted and sanctioned by Liferay is on our Docs & Resources page. We spent a lot of time listening to what the community was saying, and have made these changes as a direct response, not only to provide more documentation, but also to make the docs we have easier to find.

So what will you find? First: the Portal Admin Guide for all three supported releases of Liferay (6.0, 5.2, and 5.1) is now browseable on the site, and its contents will appear in searches. This is a big change in and of itself, because previously our documentation was locked up in PDF files which weren't easily indexed (by Liferay or by search engines such as Google). We could not have done this without our awesome dev team in Spain, who provided a way for us to import the documentation and convert it automatically to Liferay Web Content.

In addition to this, we now have more documentation. The Portal Admin Guide for Liferay 6 has been comprehensively updated and now covers Liferay's CMS and Liferay 6 specific features such as workflow. The print edition adds more than 100 pages of material, and the rest of the content has been updated to cover the new user interface. We don't have the physical print book ready yet, but watch for it soon.

As you probably know, Liferay's official development documentation is contained in the Manning book Liferay in Action, which as of this writing has about three and a half chapters to go. You can get it electronically now as part of Manning's early access program here. If, however, you want to learn about Liferay development without parting with any cash, we've written a Developer's Guide which is free. This way, you can get some help getting started with Liferay development, and if you find that you want to go deeper, you can then go get the book. Why have we done it this way? Because it gives you the best of both worlds: we love the zero barriers to entry that open source provides, and we want to make it as easy as possible for developers to learn how to build on our platform. We're also very excited to be working with a publisher like Manning who has a reach in the industry that we don't have.

You'll find all of this stuff on the new Docs & Resources page. Above all, this is a response to you, our community, without whom we could not have gotten this far. I hope that it helps you to better find the information you're looking for. We're working hard to get more materials out there all the time. Please keep giving us feedback on how we're doing, because we want to get it right.

Ever since I first started working for Liferay, I had always planned to release two books: the Liferay Portal Administrator's Guide, and the Liferay Portal Developer's Guide. They were designed to be companion books: one (the Administrator's Guide) would help users get started with Liferay by showing how to install, configure, and use Liferay out of the box. The other (the Developer's Guide) would help developers to use Liferay as a platform to build web sites. I was successful in completing three editions of one of these books: the Administrator's Guide. The other one, though, has been a bit more elusive. If you've read the Administrator's Guide, you've probably even seen the Developer's Guide mentioned in the text. And on more than one occasion, I've had to answer the question, "Where is the Developer's Guide?" 

With great (relief? fanfare?) enthusiasm, I am happy to announce the availability of the Liferay Portal Administrator's Guide, Third Edition. Now coming in at a more hefty 313 pages, this is the best Admin Guide that we have ever released. It's been updated to cover Liferay 5.2.x, which means coverage of the Liferay Control Panel. It also includes a new chapter on Liferay's collaboration suite, in addition to hundreds of other improvements, including an expanded performance tuning section.

Thanks are due not only to the many Liferay-ers who helped me out with technical details (your names are listed in the front of the book), but also to the many members of the Liferay community who have been so good with feedback and wiki articles. Seriously, the book would not be nearly as complete as it is without you. I think we are doing amazing things together and providing a great piece of software that can serve everybody from the largest corporation to the smallest non-profit.

You can go to our documentation page here to get it.

From the pen of my daughter (age three):

I am pleased to announce the availability of the Liferay Administrator's Guide, Second Edition. The Guide has now been exhaustively gone through and updated to support Liferay 5.1 (and below). But there's more than that: a new chapter on Portal Administration has been added which covers how to design a site using Liferay and how to use Liferay's administrative portlets.

Beyond the updates and the new chapter, there are new sections of documentation sprinkled throughout the book in appropriate places. For example, the book now covers how to upgrade an existing Liferay installation. The new pluggable search is also covered, and you will be shown how to configure a separate search server to use in a clustered environment.

In all, this is a significant update to the documentation. As usual, it's available as both a paperback book and as a downloadable PDF. The book has been reformatted so that it is not so large as it previously had been, and should now fit on your bookshelf nicely with the rest of your computer books. In fact, it's the exact same size as the O'Reilly Nutshell series books. Mine is sitting on my shelf right next to XML in a Nutshell, and it fits in really well.

You can get it at our documentation page here. Enjoy!!

Some people might be wondering why I've been so scarce around here. The reason for this is that I and my team have been heads-down working on a couple of brand new training courses that we will soon be offering.

We've just put the finishing touches on both courses, and I am excited about what's in store.

First up is the new Portal Administration course. This is a two-day introductory course which focuses on designing a portal, portal administration, and content management. It covers many of Liferay's included portlets, including the wiki and the shopping cart, and shows you how to administer all the aspects of a Liferay Portal, including tags, assets, documents, polls, and more. You will also get to delve deeply into Liferay's Content Management system, creating structures and advanced templates to display them.

Because this course now exists, we have removed all of the portal administration and content management stuff from the Liferay Development course, turning that course into a concentrated three-day course on Liferay development only. So now developers can take a course that covers just development on the Liferay platform, and portal administrators can take a course that covers just portal administration!

If that weren't enough, we have also added a Liferay System Administration course. This is another three-day course that covers Liferay from a server administrator's point of view. It covers everything from installing Liferay for the enterprise (both configuring bundles for the enterprise and installing Liferay on an existing application server) to administering Liferay, to plugin management, and more. An entire day of this course is spent creating a two-node load balanced Liferay cluster.

You will also learn some techniques for performance tuning Liferay, as well as how to back up a Liferay portal. There's more, but I don't want to give it all away.

Keep your eyes peeled on the Liferay training pages (under the Services menu) to see when you can begin signing up for these new courses. These courses are a direct result of feedback from those who have taken our training in the past, and it is our hope that they will serve you better.

Liferay is a big application, made up of thousands of files. That's not the kind of typical, everyday application that your system is used to dealing with.

Everywhere I've worked (including Liferay), I've made a point of advocating to the IT department that a developer needs both a different kind of machine and a different kind of configuration than the regular worker. Thankfully, that's well understood here, and I've had the freedom to pretty much configure things the way I would be able to work best.

The advent of desktop Linux, however, has been both a boon and a detriment for the community that uses it. Linux on the desktop is now much easier to use and to install, but that comes at a price: many times the configuration that is shipped by default is only optimal for the typical desktop user. For developers, like other commercial, proprietary operating systems, there are OS settings that need to be tweaked. Sometimes you know what to do right away after the install, and sometimes you run into an issue that causes you to both learn a little more about your OS of choice and to come up with one more setting that needs to be customized when you build your new box.

Recently, I've been doing a lot of training slides. This activity tends to happen in fits and spurts: I spend a bunch of time trying to get something to work, and then in a burst, I create a whole bunch of slides about it. This lets me do stuff that I haven't necessarily done before, which generally means I run into a bunch of problems I haven't had before.

This week, I've been profiling Liferay and comparing the results of different configurations. I've been working specifically with the Netbeans profiler, for two reasons: 1) It's free and open source--which means we're free to use it in training, and 2) I've never used it before. So I wanted to see if it would work for the scenario I've got going. No guarantees here--I'm still working on it. :-)

Anyway, I kept having Netbeans crash (actually it wouldn't crash--it would just become unresponsive). Checking my .netbeans/6.1/var/log/messages.log file, I found that it was unable to open any more files because of a "Too many open files" exception. At first, I thought this was a Netbeans issue, because I never had this problem with Eclipse, but everything I found online pointed to an issue with the way the OS was configured.

I use Kubuntu, which is definitely a desktop OS. By default, Kubuntu (and presumably, Ubuntu) is configured to allow 1024 open files per shell session. Liferay easily exceeds this number, and this is the problem Netbeans was running into. I found several things you can do to fix this, though, and it all has to do with tweaking the number of files that are allowed to be opened by a user on Linux.

First, take a look at your /etc/sysctl.conf file. In that file is a property called fs.file-max. This should be set to 200000 or above. On Kubuntu, this was already set properly. If yours isn't, go ahead and change it, but this won't solve the problem by itself.

Next, there's a setting for shell level file limits. You can check what your current one is by using the command ulimit -n. Mine was 1024, and that was the problem.

To change this setting, you need to edit the file /etc/security/limits.conf. Add the following lines to the file:

* soft nofile 5000
* hard nofile 5000

This basically changes the setting from 1024 files to 5000 files for all users. I had no idea how much I was going over the limit, so this seemed like a good setting. Save the file and then reboot your machine, and everything should be fixed.

So if you find yourself with this error, it's likely because Liferay is a very large project, and your default settings are simply not sufficient to handle it. Linux is by design tweakable, so it's not so hard to fix.

Here's a good story for a Friday: I'm running around today opening windows because it's hot, but not so hot as to turn on the air conditioner. I'm a little frustrated trying to get something to work, and so I want to get back to it. Because of this, I'm racing around the house trying to get the windows open as fast as possible.

Last room to enter is my three year-old daughter's room, and what I saw made me stop and smile:

She put an old diaper on one of her stuffed animals, and then put it to bed. Priceless.

Just wanted to let you know that the Quickstart Guide (upon which the below video is based) is now available! You can grab it at the Community landing page: http://www.liferay.com/web/guest/community.

It's a lot easier to follow the doc than the video. :-)