Let's build a better documentation for AlloyUI?

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