Richard Sezov

Philosophy of Writing, part 1

2011-11-04T19:24:26Z

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.

From the cutting room floor of Liferay in Action: the Ext crutch

2011-05-12T22:12:38Z

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:

Customizing Struts actions of internal Liferay portlets
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]

Liferay in Action now has all its chapters

2011-03-11T18:43:16Z

The Liferay in Action MEAP was updated today and now includes all the chapters that will be a part of the book. I still have some editing to do, but we're getting pretty close now. From the Manning announcement:

What's new:

Chapter 1, "Liferay is a different portal," has been revised.

Chapter 2, "Appray: Development at light speed," has been revised.

Chapter 3, "A data-driven portlet made easy," has been revised.

Chapter 4, "MVC the Liferay way," has been revised.

Chapter 5, "Providing your own site design with themes and layout templates," has been revised.

Chapter 9, "Liferay architecture and extension points," has been revised.

Chapter 10, "A tour of Liferay APIs," has been added.

The new chapter 10 provides a tour of Liferay APIs that you'll want to use in your applications. You can give your applications friendly URLs, organize larger applications with ActionCommands, use the message bus, schedule jobs, index your data, and more. Chapters 1-5 and 9 have been updated in response to reader and reviewer feedback.

Next, the book will be moving into production, where it will get a copy edit and will be typeset for printing.

What's next:

I have to get the manuscript for its final technical review. Once that's done, there will be another batch of revised chapters in the next update. So you can still subscribe to the MEAP, and now is a great time to do it, since the book now has all its chapters. You can get a 35% discount on it by clicking here or on any of the banners for it that you see on liferay.com.

To anyone who's been reading, thank you for your valuable comments and feedback. We're on the home stretch now!

Liferay in Action: next to last chapter added to MEAP!

2011-02-04T20:57:48Z

Well, we're marching right along on our way to completion. Manning has just updated the Liferay in Action MEAP with the next-to-last chapter, on Ext plugins. With this chapter, you learn all about Ext plugins, what they're for, and how you can use them. You also learn about the core of Liferay: what it's composed of and how it's architected. Along with this, you get a complete tour of how Liferay composes a page from browser request to page delivery. And since now all the plugin types have been covered, we discuss best practices for Liferay development, including guidelines on when to use each plugin type.

I'm currently working on the last chapter of the book, so we're almost there! Chapter 10 will discuss a list of Liferay APIs you can use that can greatly enhance your site. You'll be surprised at all the things Liferay gives you, such as large project organization, friendly URLs, view level permission filtering, indexing, and a lot more!

I'm really excited to be this close to being done. It's not too late to jump onboard the bus and get the book as I write it. I look forward to hearing your comments and feedback on the new chapter!

Liferay in Action MEAP Update

2010-12-27T17:46:51Z

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:

- Liferay's asset system, which undergirds a lot of other features

- Workflow-enabling your applications

- Adding tags and categories to your entities

- Using Liferay's ratings and commenting systems in your applications

- And if that weren't enough, how to do custom SQL queries in Service Builder!

I hope you all are enjoying your holidays. I sort of need to get back to mine, as my daughter is standing next to me waiting for me to finish this so we can go out and play in the snow. So I wish you all the best of holidays and a very happy New Year! And if you plan on taking a look at the MEAP, I hope it serves your Liferay needs or at least provides you some good, diverting reading material!

Revamped Docs on Liferay.com!

2010-09-18T03:46:24Z

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.

Liferay in Action

2010-08-24T09:58:13Z

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?"

For lots of different reasons, work began on the Developer's Guide, and then it stalled, and then it began again. Part of it is me: I find it a lot easier to write about functionality that the engineers implement than to write my own code and then explain it. Last year, though, I was doing pretty well with it and had hoped to release a "preview" or "rough" version for 5.2.

But now something really exciting has happened. Liferay has partnered with Manning Publications to release Liferay in Action, the official guide to Liferay Portal development! This is a book for Liferay developers which focuses on creating applications and web sites on the Liferay Portal platform, and it fills the same need (and then some) that the Liferay Developer's Guide would have filled.

This book covers portal development on Liferay 6. Though it is still a work in progress, you can get it right now, thanks to Manning's Early Access Program (MEAP). I have been working really hard on it for the past few months, with the desire to deliver the best possible product to Liferay developers who have been waiting so long. If you want the book early or if you feel like you want to help, you can get involved with the book right away by taking advantage of the Early Access Program. You then get the chapters as I deliver them, and can give me feedback on what works and what doesn't. If you want to get involved, head over here:

http://www.manning.com/sezov

I just want to thank all of you who have been so patient in waiting for this--we've seen your forum posts and are doing the best we can to help. I'm very thankful for Manning and their early access program which allows us to get material to you faster while it's still being produced. My blog has been rather scarce of late, but now that I can finally annouce this, I hope to keep it up to date as a journal of sorts of my progress. So even if you don't want to get involved in the MEAP right away, hopefully I'll be able to give you a bird's eye view of what's going on.

Announcing the Liferay Portal Administrator's Guide, Third Edition

2009-06-10T16:20:47Z

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.

Could this be construed as Liferay Indoctrination?

2009-03-20T18:35:34Z

From the pen of my daughter (age three):

Liferay Administrator's Guide, 2nd Edition

2008-10-09T17:09:26Z

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!!

New Training Courses

2008-08-22T19:28:10Z

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, Java, Linux, and Too Many Files

2008-06-18T19:20:50Z

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.

Three Year-Olds

2008-06-13T18:57:45Z

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.

Quickstart Guide is Available

2008-05-28T20:02:40Z

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. :-)

Liferay Portal: From Zero to Intranet in 10 Minutes

2008-05-01T15:25:09Z

A few weeks ago our CEO proposed a challenge to me: create a document that shows how to create an Intranet in Liferay in 10 minutes.

Here's a demonstration video:

Oh, and the document will be available at the Liferay booth at JavaOne.

Presenting...the Liferay Administrator's Guide!

2008-03-14T03:16:32Z

Well, it's a little late and yes, it's a little behind, but the first edition of the Liferay Administrator's Guide has hit the presses! Covering Liferay Portal 4.3, it goes over everything from installing Liferay to an application server to integrating it with other services, such as chat and workflow. There's a complete description in the blurb on the back of the book.

Writing a book is a huge job. I say that because were it not for the sheer number of contributors of material, this book would still not be done. Why? Because the research end of it alone (in this case, that's actually going through each feature, configuring it so it works, and writing up notes during the process) could take as long as it's taken so far. Once you have that done, however, you need to start writing.

I got a jump start on both of those tasks (the research and the writing) because of some great people who a) helped me when I couldn't get something working or b) contributed documentation for a particular feature that they already wrote.

So I am grateful for all of those (I attempted to list everyone on the inside front page, and I'm praying that I didn't miss anybody) who contributed material to the book: you were instrumental in getting it done this fast.

The Liferay Administrator's Guide is available from our web site as a free PDF download. A much, much cooler way to obtain it, though, is as an actual book, which you can get from here. That way, not only do you get a nice, portable Liferay reference you can take with you into the server room, but also you get to see the really cool picture our CEO, Bryan Cheung took in Langen, Germany, near Liferay's European headquarters. That's a special bonus that only appears on the front cover of the real book.

Before I start sounding like an As-Seen-On-TV commercial, maybe I should talk about where we go from here. This is only the beginning of the Liferay Documentation Project. Next on tap we have a Liferay Developer's Guide, which will guide the developer through the ins and outs of writing code on the Liferay Portal platform. And, of course, we need to catch the documentation up with the latest release of Liferay.

We also have several 4.4-based Lifecasts--online demos of how to use Liferay to build out a web site for your organization. These are authored by Jon Lyons, and he has done a fantastic job with them. You can access these by clicking here. I'll let him give you the details on those.

Anyway, that's why it's been so quiet around here on the documentation team--we've been heads-down trying to get these products out to you as fast as we could, with the highest quality we could. Thanks to all for your continued patience as we work on providing these resources!

I Drank the Kool Aid

2008-02-15T04:11:39Z

Despite years of resistance, I am now a Kubuntu user. It's taken a lot to get me here, but if you're interested, hang on to your hat.

I've been using Linux for many years as my primary operating system at home. I started off in 1994 (!) with a copy of Slackware that came with a book and several CDs of software. I managed to configure my 486DX/33 system to triple boot DOS, OS/2, and Linux for a while. At the time, I had been using OS/2 since 1992 as my primary operating system, because I believed that it was the wave of the future. But I wanted to learn Unix, and installing Linux was (and still is) the best way to do that.

There wasn't much software for Linux in those days, and getting X running was a nightmare of manually editing configuration files. Getting to high resolution (800x600) was extremely difficult, though I remember succeeding at it eventually.

In any case, I eventually put Linux aside for productivity reasons: I was a systems integrator who was putting in networks for small businesses and government offices, and I had no access to the Internet, which made much of Linux's functionality an academic exercise for me. But I kept my eye on it, looking for opportunities to use it in my work.

My next foray into Linux was with RedHat a couple of jobs later. I installed a test Linux server as a web server with an eye to replacing the IIS server I was running on Windows NT. I soon wanted to try using it as a desktop (because Windows 98 would crash on me several times a day), and began fiddling with that at home. KDE 1.0 had just come out, and it was a feature complete desktop that made the day to day use of Linux on the desktop a bit easier.

Back then, you had to install KDE by downloading a whole bunch of tarballs and extracting them to some location on your system. That was, if you could find binaries. And if your dialup connection stayed active all night while you were downloading megs and megs of data. A lot of the time, you had to compile KDE from source. It made getting up and running a tedious and lengthy process.

At that point, several people began providing RPMs of KDE for RedHat users to install. I played with those for a while, but continued to be frustrated (as did others) that RedHat would not include KDE with their distro. Instead they threw their weight behind the competing GNOME desktop, which was way behind KDE at that time. The reason for this situation was that KDE was based on a library called QT from TrollTech, which at the time was not GPL licensed, but instead had its own open source license, called the QPL. This made the software "non-free" in the RMS sense of the word, and became the whole reason for GNOME's creation. That rift in the Linux community is not a particularly pleasant chapter in the history of Linux on the desktop.

People like me who just wanted a functional desktop on RedHat didn't much care which open source license KDE used. And there were enough of us that somebody did something about it. That somebody was Gael Duval. He created a little-known distro called Mandrake Linux, which was RedHat recompiled from source, with KDE already included. Mandrake became incredibly popular and spawned a company of its own. The code base eventually split from RedHat and became a distro in its own right.

That distro, because of mergers and aquisitions, is known as Mandriva now. Gael Duval left the company several years ago, but up till now, I have been a faithful Mandriva user for many years. I am a member of their Club and so have supported the distro financially for a while. I happily installed their latest 2008 version on my Liferay-provided laptop and to my great consternation, had to deal with several issues, notably having X crash on me at random times during the day. Suspend / Hibernate wouldn't work with Compiz turned on either. When I finally lost some data in one of these random crashes, I formatted my drive and installed OpenSUSE. Why OpenSUSE? I wanted to get some experience with it: it's one of the more popular distros, but I'd never used before. I'd been planning on switching back to Mandriva once the new version came out. I'd done this before a couple of years ago when I had a problem with Mandriva: at that time I used Mepis to get me through until they released a version that worked with my hardware.

To make a long story short, stability (i.e., lockup) problems with OpenSUSE led me finally to Kubuntu. I'd been resisting going to Kubuntu for a while, because frankly, I thought Mandriva was better, and Mandriva had for so long provided everything I needed out of a Linux distro. But this was the second time new hardware refused to work well with Mandriva, and I was forced to give up on it because I couldn't find any information online in their forums or bugzilla to help me diagnose the problem.

My Kubuntu experience has so far been very pleasant. First of all, everything works. I can suspend my machine with Compiz-Fusion running and it comes back just fine. Initally, my network didn't come back after a suspend, but--and here's the big difference--I was able to find information through a simple Google search on how to fix that. I was able to compile the driver for my laptop's web cam (http://syntekdriver.sourceforge.net; it's not yet included in the kernel) without issue. On Mandriva, they'd split the kernel into a laptop version, a desktop version, and a server version and I was never able to get the driver to compile, even though I'd installed the right header packages. The Skype beta that supports webcams on Linux is available in the (K)ubuntu repositories--not so for Mandriva. I could go on.

Also--and this is inexplicable to me--Kubuntu is faster. It just does everything faster. I don't understand this: it's still Linux, so all the software should be the same. I'm still using the ext3 file system, KDE, and all the same software. You've probably seen other people's blog entries on liferay.com talking about how much faster Liferay compiles on (K)ubuntu than on Windows. Well, they're right. Except it's also faster than other Linuxes. I don't get it.

So at this point, I think I'm finally going to say goodbye to Mandriva after many years of using it. I started with them because I needed a system that just plain works. Kubuntu now does that better than Mandriva, in my experience. After several years of resistance, I have finally drunk the (K)ubuntu Kool Aid. I hope I'm not too late to the party.

Documentation Milestone Reached

2008-01-23T21:15:08Z

First of all, a belated Happy New Year! This is my first blog post in the new year (and in the new theme), and I'm excited about what I have to report.

Last night I finally finished the first draft of the Liferay Administrator's Guide. It's a bit pared down from the outline that's published out on the wiki, but that was done in order to get the book out as quickly as possible. For the second edition, I will be fleshing it out into the complete outline. The portions I've skipped documenting have to do with the user interface of the portlets, which is not generally something we get a ton of questions about. Nonetheless, it is important to document them, and that will be done after the first version of the Guide.

Right now it's coming in at 181 pages. I've spent the day (and probably will spend most of my time this week) going back through and editing. Once this is done I'm planning on sending it out internally for review. But we're getting real close now.

After the editing and reviewing is done we'll make the document available, and then it will be on to a dual task of updating it for the 4.4 release and finishing up the Liferay Developer's Guide. So there's still a lot of work to do, but we're definitely getting there!

Liferay Plugin Development Guide

2007-12-14T19:22:02Z

Quietly and without much fanfare, we have released the first document in our new Liferay Documentation Project. This is because it's a rather small document, but it fills a need to have some instructions for using our Plugins SDK available. Since the Plugins SDK is now the preferred method for creating portlets and themes, not having it documented was sort of a glaring omission.

This is also the first document to give an introduction on how to create Liferay themes, culled from our open document project, the Liferay wiki (where all the content is licensed under the same MIT license we use for the source code). Special thanks is definitely due to those who worked on the Themes document out there on the Wiki. This would have taken a lot longer to produce without the support from our community.

Eventually the Plugin Development Guide will get merged into our larger Liferay Developer's Guide, which is still in-process. Our next release will likely be the first version of the Liferay Administrator's Guide.

Things I Learned at the Liferay Retreat

2007-12-11T21:59:52Z

This is a list of things I learned at the Liferay retreat.

You should not give Nerf guns to developers with pent up energy from sitting around coding all the time. Pandemonium will ensue.
Many Liferay-ers are multi-talented. We have singers, guitarists, dancers (sort of), people who are good at sports, and, um, monkeys.
There is debate over whether you need to be naked to live in an igloo.
People from Canada do not live in igloos.
Don't challenge Brian Chan to a freethrow contest.
If you are an innocent bystander in a Nerf gun fight, a well-known Liferay engineer will hide behind you to avoid being shot, while he shoots at others.
Caris Chan is a very brave woman. She can stand unflinching while 5 guys at least double her size come rushing at her, each with a metal can and a golf ball.
Joe Shum can fit an infinite number of golf balls in his pockets.
I am not the only one who doesn't know how to do regular expressions.
A football that drops over a cliff is retrievable.
New Jerseyans like me think anything with a drop of more than 10 feet is a cliff.
It is very hard to draw out 17 words from Romeo and Juliet into a 60 second video.
Have you heard of the Amazon Kindle? It's this awesome new book reader. You can store tons of books on it, and it has an e-ink display that looks just like paper! It's also wireless too, so you can be connected all the time and just transfer books....
People in the Malibu area don't call the cops when multiple Liferay employees get lost in their neighborhood looking for their retreat location which is so remote that neither Google Maps nor multiple brands of GPS devices can find it.
I swear I found the exact spot Arnold Schwarzenegger dropped Sully off a cliff in Commando.
I am way too impressed by cliffs and things dropping off them.
People will walk away from your conversation when you start talking about the difference between classical and presuppositional apologetics.
Technology people who work for an Internet company can survive a weekend with no Internet access.
Herding a bunch of engineers into a static schedule is akin to herding cats.
Saying "Enterprise. Open Source. For Life." in German is not that hard.
A guy with a sprained ankle can still bear most of the weight of a grown man as he is carried into his room on video.
If you are not on Alex Chow's team, you will have to physically restrain him in order to take his picture with your team.
It is possible to hit somebody who is lying on a massage table in the side of the face from across the room with a Nerf gun.

And finally:

I work with a fantastic group of people, most of whom I didn't know until this weekend, and they all made me and my family feel very welcome.