Developing Right Documentations for Frameworks

Frameworks always come with documentation for developers to fully understand the framework’s function.

It is the first document read by developers as soon as they have acquired the framework and was convinced to use the framework in developing an Ajax based application.

But not all frameworks are built in the same manner. Some of them are fully comprehensible while some just increased the confusion on how to handle the framework. Documentation should be the author’s way of extending the usability of the framework.

The framework will be judged not only in its efficiency but also in documentation. A well documented framework will shorten the time frame for website or application development and will ensure that the framework is used to its full capacity.

Here are some tips on how to build an efficient documentation for frameworks:

1. Write them yourself – This is really basic but there are developers who opted to let others write the documentation for them. No one knows how to deal with framework more than the author.

If it is a collaboration; make sure that the documentation is written and edited by the entire, or at least most of the development team.

It is very tedious but writing documentations for an application should be part of your project plan.

You should give time in writing documentations in your project plan to ensure that you are coming out with a powerful and easy to understand framework.

2. Well structured – If you are writing a documentation, don’t write them as if you are making notes. You will be the only one who will understand the documentation and will be practically useless for the adopters of your framework.

Start with the general idea, i.e., the purpose of the framework and what it does and carefully move into more specific areas of the framework.

When you are writing documentation, think as if you are trying to explain how these things work and how the framework should be executed. A well structured documentation will go a long way not only for other developers but also for the author.

3. Develop a Wiki – The easiest way to build documentations to seek the help of other users. You can build a wiki page for your documentation so that other users can contribute to the understanding of the framework.

You will still have the power to control the texts entered in the wiki page so the quality will stay the same.

But do not just create a wiki with a blank page hoping that users will make an extra effort in building a wiki. This will just increase the confusion among developers.

Write the complete documentation first and post them in a wiki page so that others will have the ability to contribute without destroying the basic understanding of the framework.

Writing documentation is tedious task for most developers since they would have to explain the framework from the scratch. But this extra effort is required for developers who are aiming to propagate their framework. It is not easy but it should be done for the development of the framework for Ajax based applications.