Zeno Rocha

Let's build a better documentation for AlloyUI?

2013-05-31T22:39:32Z

When I first met the AlloyUI project was a little bit hard to understand all the functionalities it provides without looking to the source code. Then we made a new website that shows how can you use each component with some code snippets.

That was great, but how can you check which are the configuration options available for each component? For instance, you know that there are options like contentBox, height and width on Carousel, but they are not the only one, there are plenty more configurations that you could use.

That's why we have the API Docs, that is generated based on the source code, pretty similar to JavaDoc. The only problem was: most part of the source code doesn't have documentation at all, so the API Docs became outdated :(

We had to change that, so after a couple days of hard work we added the necessary markup for documentation on all attributes, properties and methods. So now we are able to document, we just need to actually explain how each part of the code works.

Current Status

At this moment, there's a total of 109 JavaScript files on AlloyUI core.

29 are documented;
64 needs to be documented;
16 can't be documented.

To track what files are documented or not, we made public this status list on Github. If you want to join us on this quest to make AlloyUI better, make sure to check this list to find out what needs to be done.

Contributing

Let's say you want to help and just discovered that aui-autocomplete.js needs documentation. If you navigate through the code you'll see a lot of attributes, properties or methods that doesn't have description yet, for example:

All you need to do is understand what that piece of code stands for, explain it and send a pull request :)

Bonus

Additionally, if you have Yogi Alloy installed and want to check how the documentation will look in the website, you can run ya api-watch to generate the API Docs locally and watch for any changes.

New Theme

Together with all those new things, we're also introducing today a new theme for API Docs! Forget the old one:

And start using the new one today!

Conclusion

This task can't be done by a single person, there's a lot of code to document and we need your help. Here, at Liferay Brazil, we started this thing called Daily Docs, so everyday at 5pm an alarm rings and we need to stop everything to spend 10 minutes improving the documentation of a certain component. Those kind of initiatives could be very helpful, so if you care about this project, please join us :)

AlloyUI and the importance of CDN

2013-03-04T18:27:21Z

Some weeks ago we announced the preview release of AlloyUI 2.0. One of the cool things about it is that now we have a pretty new CDN (Content Delivery Network). So instead of downloading AlloyUI to use in your local environment, you just to need copy and paste this line of code and start using it.

	<script src="http://cdn.alloyui.com/2.0.0pr2/aui/aui-min.js"></script>

But it was only available for AlloyUI 2.0, which is not integrated with Liferay yet, then Liferay community wouldn't benefit from it.

That's why today we have some news to share, all versions of AlloyUI are now available on CDN to use in production or to download as a zip file \o/

PS: Check this table if you don't know which version is being used by Liferay.

Why it's so important to use a file hosted on a CDN?

Basically for performance improvements, we'll dig into some of them.

Decrease latency

Let's say you are in China and your server is in Los Angeles. When you load a file the browsers sends a HTTP request that will go across the globe until reach your server and, as you can see, it takes time.

However if this file is hosted on a CDN it will be distributed across many different servers in the world. So when you make a request, it will look for the nearest server, which decreases latency time a lot.

Wikipedia: (Left) Traditional scheme of distribution - (Right) CDN scheme of distribution

More parallel downloads

Browsers can't handle too many parallel downloads per domain.

That's why hosting files in different domains is a good performance tip.

Cache

Let's say you visited a website that uses AlloyUI hosted on CDN, as soon as you load it your browser will automatically cache it in your machine. Then if you visit another website that uses AlloyUI too, you don't need to download all those files again because you already have cached them.

What's the real benefit?

Let's try those performance improvements in real life. My experiment will load the exact same file using a CDN and don't using it.

Didn't use CDN:

When you load this file, that is not hosted on a CDN with a 10mb internet connection, you take 1.27 seconds with 404ms of latency.

Use CDN:

But when you load this file, that is now hosted on a CDN with the same internet connection, you take 314ms with 155ms of latency.

That's a 75% decrease and this is only one file!

Now imagine a lot of modules and its dependencies being loaded, it will cause a significant difference.

Conclusion

And that's all folks! If you have any questions please comment below :)

I'm the #50 most active contributor on Github, so what?

2013-01-09T22:15:27Z

Today, Paul Miller released a nice list of the ”Most active GitHub users”.

People started to talk about it and suddenly I received a lot of congratulations messages for being the #50 most active contributor on Github.

I was pretty happy because this is a chance to show how Liferay employees are strong in the open source community. But I was mostly surprised, since there’s almost 2 million users on Github and even because Linus Torvalds, creator of Linux, was behind me!

That was pretty nice for my ego, but let me explain what this ranking means for me.

Quantity != Quality

The first thing is, I’m not better than anyone.

Just because I made 100 commits more than Linus, it doesn’t make me a better contributor than him. Actually I could do 10,000 commits more than him and I would still not being a better contributor.

The only thing that these numbers shows is: those people on the list put a lot of effort on open source using Github.

And this is true, I've been working hard on the new AlloyUI and many other projects out there.

People just don’t get “commits”

We all have a lot of tasks to do daily, so how to deal with them using Git?

Let’s say you have a task called “Redesign my blog”.

Some people start coding it, making a lot of changes and when it’s finished: git add . && git commit -m "Redesigned my blog".

This is so wrong. What happens if you want to revert just a single improvement that was not so good there? You’ll need to revert the whole commit.

That’s why you have to break your tasks into sub tasks. It seems like a basic thing, but people just don’t do it.

1st place

If I had to guess who’s going to be in the top of this list, that would be TJ (@visionmedia).

He’s doing an incredible job in the NodeJS community, so congratulations man, you deserve it :)