Let's build a better documentation for AlloyUI?
General Blogs May 31, 2013 By Zeno Rocha Staff
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
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.
- 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.
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 :)
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!
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 :)