Liferay Documentation Project

While it's nice to blog about some of the tools I use (see the below posts on VirtualBox and the Lomboz plugin for Eclipse for more info), I figured I should probably mention some of the stuff I'm working on for Liferay.

Though I'd like to think I was brought in because of my 1337 5k1||z, the fact of the matter is that I have only one ingredient that separates me from others (and it ain't my not-so-1337 5k1||z): I have an English degree. I'm the only developer I know who actually likes to write (though I am sure there are more of us out there).

It's pretty well known in the community that documentation has not been the strongest aspect of this project. In my previous life as a Liferay customer, I too was bitten by the lack of good documentation to help a poor newbie understand how to implement this incredibly powerful--but complicated--piece of software. So I'm going to try to fix this by creating some new documentation that is both well written and comprehensive. This is no small task, and I will be relying heavily on contributions from the Wiki (which I see as a content staging area for official documentation) and from others, both inside of Liferay and from the community. Hopefully, we can make the documentation every bit as good as the product itself!

I hope to have a lightweight version of the docs for 4.3 ready by the end of the year (I do have other responsibilities I will have to balance with this project). And "lightweight" is going to be in the hundreds of pages. Once that first, lightweight edition is complete, it will be expanded to include other topics. I have posted the full list of topics I'd like to cover over on the Wiki here: http://wiki.liferay.com/index.php/Official_Documentation_Outlines.

Of course, we want the documentation to keep pace with the release schedule of the product, so once we're done "catching up" with where the project is, new editions will be released for every product release we have.

The hope is that this will go a long way toward addressing the issues with the Liferay documentation. We want Liferay to be the best Portal out there, and it'll never be that if its adoption is hampered by a lack of complete documentation.

I'll have future blog posts about my progress, and may also post questions to the community here, so keep watching this space!

Gotta get back to writing now....

13 Comments

Please sign in to comment.

This is great news, and much appreciated... I will say, in fairness, that Liferay's docs are in much better shape than than many other software applications I've been exposed to. Having such a plethora of resources, from formal PDF "manuals" to Liferaypedia to forums - helps overcome weakness in any one of the areas. (Not saying Liferay's documentation is "good enough", it is just better than many other projects).

To use this reply as a soap box to address a pet peeve of mine with a lot of on-line docs: Please make sure pages are dated and noted with applicable versions. On the internet, documentation never dies, and more than once I've been bitten but working with obsolete docs because they weren't dated or versioned. Nothing is worse than spending a day trying to get a web-app up and running and then realizing the docs are referencing something like Tomcat 0.1 or something. </soapbox>

Thanks again!

Please sign in to reply.

nice nice... we should just tell people all our docs are written in java =)

Please sign in to reply.

Rich,

So glad to see that it's one of your passions to write. It's certainly not mine!

Please sign in to reply.

Hey Vaughan,

There's already an effort underway (started before I got here) to categorize the docs in the Wiki, by Liferay version # and subject. So for the online docs, hopefully that will help! For the manuals, I want to marry a version of the manuals with the version of Liferay it goes with, in a similar fashion to the way commercial applications do it.

There are a lot of corporate developers out there (and I was one of them) who like nothing better than a nice, thick manual. I think that's why the computer book publishers do so well! :-) So we'd like to fill that need while at the same time using the Wiki for your more bleeding-edge documentation. And of course, I agree with some of what's been said about the Wiki: I'd love to be using Jorge's enhanced Wiki portlet rather than MediaWiki and keep it all "in house" so to speak. The more we eat our own dog food, the more motivation there is to improve the features.

Please sign in to reply.

Good evening Rich-

The ability to learn is the singular "personal skill" I value most in myself (and any employee, for that matter.) Having good documentation is the resource tool needed to apply that skill, in nearly every situation. In my own job, documentation projects - everything from production work processes to smoking policies - are being migrated to using Liferay to provide the unifying presentation structure. Hence my interest in the wiki portlet...

Anyways, since it is on my own mind quite a lot, what are your thoughts on unifying / merging the all the documentation sources into a single environment. I see the problems with getting wiki docs formatted for paper printing when needed. But, almost a bigger issue is keeping the 'paper documents' current in such a rapid changing environment.

Again, to my own job - we are now looking at pretty much giving up on keeping up with the old school docs (word files, etc) and moving everything to either wiki or other online content (using the CMS system).

I'm also willing to contribute what I can to the community, so let me know if there is anything I can do to assist.

--
Vaughan Schmidt

Please sign in to reply.

Rich, since there are no emails for liferay people, no forum categories for these discussions, and not even a blog or wiki for them, I am forced to contact you this way.

Today, i have to understand the theme system, and from what I have seen, the theming has changed more than a few times. Before I waste my day trying to get up to speed with obsolete docs, could you please point me to the most reliable materials on creating my own theme by modifying one that exists. If there isn't one, and you intend to write one, please keep it simple. In my experience with other products, the best way to do this is a SIMPLE document with only a few key steps, and the least amount of confusing verbiage. People can always get the details in other documents. A "starter" should simply be a few key steps with minimal explanations. Just "Do this, this, and that." Done! Too many "Starting Guides" so load up the verbiage, that they no longer feel like jumpstarts, but rather, full blown tutorials. I urge you to not make that mistake in your new efforts. I look forward to any theme docs you can direct me too.

Please sign in to reply.

Hey Vaughan,

Thanks. Right now I have lots of source material (original docs, training stuff, Wiki content) that for all intents and purposes, is in a big heap. I created outlines of the material I think will be most helpful to cover, and then we collaborated on it some internally. That's what's posted out on the Wiki.

I have a subset of that outline that I'm working from as a first stab at the documentation, because I don't want too much time to pass without having *something* released. Any little bit will be more helpful than what we have currently.

The next task, to take a page from David Allen (I highly recommend his book, Getting Things Done), is to take the content we have in our "inbox" (Allen's term) and go through it from the top of the pile to the bottom of the pile until we've fit it into the categories suggested by the outlines (or create new categories for it). That's sort of what I'm trying to do.

Of course, it's not really in a big pile; it's spread out over both internal and external resources. So I have to be careful not to get bogged down in the collection / sorting process so that I still have time to write / edit and get something out the door in a reasonable amount of time. That's really the big challenge.

Helping with the categorization of Wiki content would be of incalculable value to me. I want to get the categories mapped closer to what's in the outlines so that that is easier to do. Right now I'm slogging through the portal-ext.properties file, trying to document every option in there (a lot of it is done in the file comments, but a lot of it needs clarification too). So I'm sort of trying to stick to my outline and get to the categorization tasks as I reach that particular subject (which is why you haven't seen too much activity from me on the Wiki yet).

In any case, thanks for any help you can offer!

Please sign in to reply.

Hey Matte,

There is an article on the Wiki here: http://wiki.liferay.com/index.php/Themes. There is also a training presentation available on this page: http://www.liferay.com/web/guest/documentation/4_3/development#presentations I haven't gotten to that portion of the documentation yet, but I was recently in your situation, as I had to create a custom theme for my former employer when Liferay 4.3 was still in Release Candidate status.

My process was to take the default theme (Liferay Classic) and simply modify stuff until I got the look I wanted.

What I would recommend now is to go to the Plugins page and grab one of the custom themes there that most closely resembles what you want to do, and then customize that. You can also learn more by comparing two themes (I would suggest comparing a Liferay, Inc. theme with a community theme) What you'll get by doing that is:

1. An example project from somebody else doing Liferay customization
2. An example of how to package your theme in a .war file for hot deployment
3. Examples (most likely different) of how to accomplish similar tasks

That's the best I can offer, both in advice, and in pointers to documentation at this time. It's going to take time to get the docs out, but I'm working as fast as I can.

Thanks for your patience!

Please sign in to reply.

Ha! Reply buttons! (Thanks Jorge?)

Rich, thank you. What about renaming the custom theme. In some systems, that's a royal bear. Can you shortcut things for me?

Please sign in to reply.

Matte,

Do you mean changing the name of the theme? That should be pretty easy: modify the name in liferay-look-and-feel.xml, undeploy the old theme, and then redeploy the renamed theme.

Please sign in to reply.

Hi Rich,

Just to be sure I understand and not become more hinderance than help - You want to go through the wiki (Liferaypedia) and check all articles for being properly categorized?

Also, on occasion, the categories might need to be refactored to bring them more in-line with your general outline.

I will be glad to start on this, to my ability, but don't want to start firing off changes to existing category system unless the Liferay team is on board with what is happening.

Feel free to contact me direct if needed to sort out details vaughan<<<at>>>schmidtusa(dot)commercial.

Please sign in to reply.

Hey Vaughan,

Thanks for your help! I discussed this with Jorge (who has been doing the bulk of the categorization of the articles), and we feel it's best at this time to use the existing categories that are out there. The reason for this is that since we are looking to move the Liferaypedia to our own Wiki, we only want to do the large recategorization once. :-)

So if you have time to go through some articles and add them to the categories to which they should belong, that would be great, and thanks a bunch!

Please sign in to reply.

Rich,

Will start as soon as I get back from road trip - maybe this coming weekend.

Thanks,

Vaughan

Please sign in to reply.

Menu Display

Blogs

Category Filter

More Blog Entries

Liferay's wiki and why usability is so important

Apple vs. PC... My encounter that changed my life...