Friday, October 19, 2007

Release 0.1 Finished !

So Today, i finally finished the "Release 0.1" of my project which was as following

Release 0.1

Goals: Document the following Storage API Interfaces

Basically, the first thing that was needed to be done was to start reading about the Storage API documentation that already existed on the MDC website. It was a pretty interesting read, because it made me understand how the actual Storage API system works and how each interface and their function works together to create this secure and efficient structure of bundled interfaces that makes up the Storage API.

After which, i started reading into the Storage API IDL files that contain information about set of interfaces that lets extensions store data in a local database. Now in my opinion, the IDL files are very helpful for understanding the structure and functionality of related set of interfaces. It shows you the available methods, attributes, constants and lots of other dependency attributes that makes up an interface. The impressive thing is that each method, attribute and constant have comments associated with them, so it is really easy to understand what is going on inside the interface and how each attribute and method is working together or with other interfaces to complete their given task. Not only that, most of the time, there existed a general comment about the functionality of main interface itself, so even before reading into the methods and attributes comments, the main general comment information gives you detailed knowledge about functionality of interface at large.

After i was done reading about the IDL files, i started documenting the Interface Reference Documents and to my surprise, the process is very similar to documenting a wiki page. Most of the syntax was similar to wiki syntax like URL binding and formatting. The good things about this documentation styles include how easy and user friendly the documenting part is, it bends to user needs and makes it very easy to input redundant information without scratching your head or doing any excess work.

At first, i just started documenting the IDL interfaces into the respective MDC - Interfaces Documentation section. But i wasn't following any set of rules, because i just looked at some existing examples of interface documents on the MDC website and i tried to mimic their style of documentation structure. It took me at least a 24 hours+ to get all 5 interfaces documented and after i was done, i found out that the way i documented them doesn't meet the documentation standards of the MDC documentation rules. Which was a waste of time and then Eric Shepherd guided me into the right direction of applying standardization process for my documents.

So basically i rehashed everything into the new standard style of documentation and the work was done in couple of more hours. It was a really great process of carrying out documentation for such important API's but at same time, i was bit disappointed in some area's, especially when certain users would edit your document without any given feedback and just change it to their own style without telling you what did you do wrong? So i ended uo scratching my head couple of times and wondering why some unknown person is editing my Article file? But after talking with them about the matter, it ended up being personal preference of following standards. There are many ways to document at MDC website but there is only one effective way of doing it, so this was the lesson i learned in this Release 0.1 of my project.

Also, much of my Thanks goes to Eric Shepherd for helping me out during the harder part of documentation and always correcting my mistakes as i moved forward with the documenting. If it wasn't for him, this documentation project could have ended up being a big disaster but Eric helped me out on many difficult steps and guided me into the right direction of documentation. Thanks Eric! Also i have to say that the open source community for documentation is really awesome and generous, i didn't feel any pressure from anyone on my documentation process. Especially, if i did something wrong, i wasn't corrected harshly on my mistakes but i was rather encouraged and guided to do things in an alternative manner without any harsh critique or pressure. It makes you feel that you belong to a great community rather than making you feel like an outsider.

I would love to hear feedback about my work and if someone has any comments or critique, feel free to leave a comment here. The interfaces links are parsed on the top of this article. Thanks for reading and good luck with your project.

No comments: