Function Documentation

WordPress Function Documentation Progress

What is Quality Assurance?

Quality Assurance is ensuring the quality of a product. It is an ongoing process that never ends, or at least not during the life of the product. Quality Assurance in open source is a more open process and anyone can help.

It involves testing, documentation, and automated testing. Testing is the most important factor, but documentation is equally important. Actually, Software Quality Assurance is a paradigm that involves a great deal more, but for the purpose of this discussion, I’m going to limit this to just the above three.

What it means to the User

When you commit to Software Quality Assurance, you are telling the customer and user that you have a policy in place that will hopefully prevent a majority of preventable bugs from occurring before the product is released. In the likely event that a bug is found, there is a policy in place that ensures that it will be fixed and prevented (in most cases) from occurring again in the future.

It also says that there is detailed documentation for both the users and developers which extensively covers the topics that both groups will want to know. Extensively covers the known areas and areas that have been questioned about in previous versions. Covers the more difficult areas better and with more details than “simpler” topics that users and developers should not have any problems with.

Solving Issues

Users, testers, and developers all help with the process. The user can make a request for a new feature that will improve the product or report a problem in the product. The testers will usually beta test and test versions of the product before it is released reporting any issues that come up. Developers will take the reports and create patches that fix the issues for the next version.

Developers will also write test cases that check whether the problem is fixed and if the problem reoccurs in a later version. If the problem does reoccur then the problem is immediately known and can be rechecked until the regression is corrected. If the regression was intentional, then documentation would have to be updated and other developers updated on the change.

Writing Documentation

Writing documentation should be concise, tutorial type explanations in language that an user and/or a developer will understand. For open source, I would just recommend writing something as close as possible to this style as you can get and cut the extraneous details (ex, I don’t want to know about how you used it in your project and the history, unless it further explains the purpose of the function, sometimes it is useful, other times it is not).

Not everyone is a professional writer (myself included), but there are enough people who are that if you give them enough information, they can edit it to where it is better. I write with the assumption that someone is going to look at what I wrote and point out mistakes and hopefully, instead of cussing me, will actually move to fix the mistakes. On Wikis, this is very simple process, on this post however, they would have to send it to be me personally or export it to their blog or wiki.

Testing Software

You are testing that the software works (well, yes you are for those who are disagreeable), you are trying to test whether the software breaks. Therefore it makes more sense to input invalid data to see if what is expected happens or not. Developers (indeterminate amount, I have this problem, so I only speak of myself and the general stereotype of developers with testing their software) have a habit of only using valid data.

You only know that the software works if you enter something invalid and it didn’t break on that input. If it breaks on invalid input, then there should be a check in place that either automatically the problem or informs the user of their mistake. There is also automated testing, which automates the lower level testing and higher level testing which automates some of what users do.


January 18, 2008 Posted by | Quality Assurance Series | , , | Leave a comment

New Documentation causes old Patches to go stale

The issue is that the line numbers will no longer match up and DIFF does not take similar lines in account all of the time. It will on your own system, since it knows what you added and can apply you additions back after it commits other changes from head. Doesn’t always work, but works often enough. The problem with patches is that they are a snapshot and don’t update.

The recent phpdoc style documentation that has been added to a lot of files, will cause a lot of previous patches for those files to go stale. While I believe it is better to have the inline documentation, than to make sure that all patches are able to be committed. I think it does put an burden on those who submitted patches and have to do so again.

I’m potentially sitting on many files which, if they were committed would break almost all of the wp-includes patches. However, if all of my patches were committed, it should only be a one time event.

I just realized this after I had my patches go stale, not from documentation, but from another mass change. I didn’t realize that it had a potential to affect many people people than myself. However, I’m sure documentation will help more people than it will hurt. It shouldn’t be that difficult to resubmit stale patches from old patches. If too much had changed, then the patch was already stale.

January 5, 2008 Posted by | WordPress | , , , , , | Leave a comment