Monthly Archives: December 2007

WordPress Documentation Informal and Unofficial Roadmap

Posted by Jacob Santos on December 31, 2007 3 comments

I would totally love it if WordPress had all of its functions documented. It could put WordPress with higher respect with developers. A lot is put on with the Codex, but the Codex is unstructured and doesn’t cover the complete depth of WordPress core and outer edges.

It is true that pieces can be picked up with the codex and trips to the code would allow others to pick up the rest. The WordPress API isn’t as difficult as some applications, so it has done without and flourished without a complete function documentation for a while.

That should change and is changing. However slow, it is quite boring to write documentation and depends on the mood. Realistically, it is very easy to get bored of it after working on it for a few days only to jump back on after taking a break of a few more days.

Documentation Process

For me, the way I’m now writing the documentation is by first going through and adding PHPdoc style documentation to all of the functions and then going back and adding @since information. Well the complete process is as follows.

  1. Add phpdoc style documentation going down the file to all functions and others that can be documented. Usually just a template which I copy and paste.
  2. Going back up I add the function name as well as @since
  3. Going back down I try to add short description information if I can, but definitely the parameters and return type information.
  4. Going back up I complete as much as possible the long description, but definitely the short description.
  5. The long description that is still needed, I usually ignore until it either comes to me or I want to finish the documentation for the file.

It might not seem like much, but on average documenting a function can take anywhere from 10 minutes to between 30 minutes and an hour and the more difficult and longer functions.

Old Style Documentation

There have been attempts to document the code before, but the extent is no where near the level of the documentation process. It is likely that because documentation does cause minor overhead to the PHP execution that a lot of documentation would slow WordPress down. However, that should not keep the documentation from the core.

If someone really cared about removing overhead from comments, then they’ll most likely do premature optimization and remove as much white space as possible also and combine as many files as possible. Premature, as the most overhead is likely with the database.

A few projects have noticed an increase and so have a build environment which has the comments, nice format, and split into multiple files and then through the build process compress and combine the files. If someone wanted to squeeze a few milliseconds, then be my guest.

The Roadmap

To me, it would be a pipe dream to think that all the functions in wp-includes would be documented before WordPress 2.4 comes out. However, I would very much like to complete the documentation in the folder before 2.5 comes out. In that way, the core development team can keep up with documentation themselves and the hardest part would be complete.

The team has started to make sure that any new function that goes in gets documentation, which should stop the flow of undocumented functions. However, it would be better if more people offered to help with the documentation. The standard is there and the support is there.

WordPress 2.4 is moving the business logic from the presentation layer in the admin panel backend. Therefore, those functions should also be documented. Hopefully, I hope to also have those done before 2.5 is out also, but going off what I have currently done and how much I have to go to complete wp-includes, I’ll be pushing for WordPress 2.6.

After the Function Documentation

I plan on focusing more on the unit testing and DocBook type documentation. It would be great to get WordPress to the level where has complete unit test coverage of the WordPress functions. Covering regressions, as well as bugs.

It would put WordPress on a higher level with developers, in my opinion, if I know that whatever code I applied went through unit tests to make sure it didn’t cause any regressions and actually fixed problems.

There is someone working on this and since it is supported by Automattic, should be continued without outside help. It would move the test coverage along if more people helped out, because user testing can only pick up so much.

The next step after the unit tests or automated tests, is acceptance testing. Which would automate portions of problems for users and test for common failures.

With an comprehensive WordPress User Guide and Developer Guide written in DocBook markup, it would allow easy access to common answers to users’ and developers’ questions. It would also remove the need to traverse the sometimes difficult to navigate codex. The guides would also be condense enough to provide pin point details instead of trying to describe everything as much as possible. With shorter amount of text, more people will be more willing to actually read through the sections to where they need to go.

WordPress Documentation Plans

The codex is not bad, but it can be improved for both developers and from the work on the user guide and developer guide, long portions should be moved back to the codex to allow for further modification and improvement.

The best thing about the DocBook User and Developer Guides is that they are completely translatable and multiple versions can be available on the same site for those native users. The User and Developer Guides would prevent translators from having to translate the huge amount of text in the codex to provide simple answers.

It is a hope, but there is only so much time. My attempt is basically to jump start the process, so that others that come after me won’t feel as overwhelmed as I do now. To my knowledge and to those that came before me, I believe they also shared my hope. It might have taken one or two years before I came along and put forth a small amount of effort. However, if I don’t get the documentation finished, I believe that some awesome person will come after me and finish what many others have already started.

Possibly Related Posts:


Which hosts are still running PHP 4.2?

Posted by Jacob Santos on December 23, 2007 Comments Off

Can you do the rest of us a favor and I don’t know, upgrade? For Christmas!

Checking the statistics, it seems that there is still a small percentage running this. I have found a few hosts offering 4.3.x, I have yet to find a host that offers 4.2 hosting. I wonder if those hosts running PHP 4.2 are dedicated. I wonder if they have applied the security patches or locked down their server.

I would rather use the argument, “Support PHP 4.2? But no one runs that version anymore!”

That would be a false statement or a lie since I already know beforehand.

Merry Christmas! (for you Christians or anyone that worships Santa, Happy Holidays for all the rest of you).

Possibly Related Posts:


If I was on PHP Internals this past month

Posted by Jacob Santos on December 8, 2007 3 comments

I was about to break my silence from PHP Internals over the discussion about namespaces. Not that I could have done anything sexy, like make a patch and an implementation that fixes problems pointed out by another. It is difficult sometimes, to not put your head up your ass.

I agree with Sean Coates. I think Derick put some good points out there, but the rebuttal was awesome! Nothing against Derick of course. This is why you leave the big discussions to the adults.

In this humble child’s opinion, I would have rather see an imperfect implementation of namespaces. While it might create some backwards compatibility issues later, I always had faith that a better implementation would be made sooner or later. However, it appears that the implementation might be better, sooner.

Thanks to intelligent people that actually put stuff out there. You’re awesome. A lot of love also to the author of HTTP extension (beautiful, just beautiful).

Possibly Related Posts:


When you need to use a online store like StoresOnline

Posted by Jacob Santos on December 6, 2007 1 comments

A followup to Stores Online Lunch that a went to. I was talking about Ebay and Amazon, and the discussion went into when you would use a service like StoresOnline[1] with someone I know.

The details of the discussion are not relevant to this post, just the rant I went into about StoresOnline.

My point was that someone should first shop their product at smaller sites first, which customers have better trust in. The guy agreed. It makes sense that this would be the case, you wouldn’t want to spend all of your money with a product that you don’t know if anyone will buy or not. Well, at least not with your own money.

First Steps of creating a product

If you have a product that you wish to sell, then develop it. When you have finished, answer these questions.

  1. How long does it take to develop the product?
  2. How much money did it take you to produce your product?
  3. how would labor be if you take how long you worked on the product between minimum wage to 15 an hour?

Find a product online or at a store, if you can, that matches your product. If you take 2 and 3, add them together and it is more than the price at the store, then you have a problem. If the product is even less than 2 then you have an even bigger problem.

How can you develop a product that costs more than what a person can get at the store? Your product would have to be of the top quality to be even considered, but to get that, you would have to first sell your product.

Now, what you can do, is take a hit initially in order to gain a good reputation. If you love what you do and can afford to do that, then so be it. If you add extra costs, like hosting and everything else that goes into running an online store, you’ll get nowhere.

Second Steps of creating a product

Do Research. Lots of research. What products are already out there, what do they have that you don’t have, how much would it cost for you to manufacture the same product? There are a lot of areas that you can research. One of the most important is how to get raw materials (if needed) to produce your product cheaper.

Patents. You have to figure out if there are any patents out there that you use to produce your product and if so, then you’ll need to redefine your product. It would cost you even more money, if you find out later that your product uses a patent from a company and that you need to pay them.

Research on developing products. Developing products isn’t new, many people do it and do it very well. You can learn from them by reading their books and learning from the best. You could just jump in and hope that you succeed, many people do and succeed, however, if you really want to go further, you’ll put in the extra effort.

Reality: You can’t build a business working 4 hours a day

Good luck trying. Most people who are surveyed after starting a brick and mortar company say they work over 60 hours a week at the beginning. Even if your company is online, I wouldn’t expect to work less than full time once the company gets rolling and the more hours you put in the sooner the ball will be able to get rolling.

Anyone that tells you otherwise is trying to scam you. Certainly, there might be a few areas that don’t require as much effort, but the rule of thumb is that you will be working your ass off, until your company is making a profit and you can hire other people to work their ass off for you.

Reality: When first starting you don’t need a large storefront

People do just fine selling crap on eBay, Amazon, and other online storefronts. So many online places are doing it now, that you don’t even need a web site starting out. At least not one that requires anything more than a few static pages detailing what your company is.

Here, when starting out, just get cheap hosting at a place like Yahoo! or just buy a cheap template (there are many out there) and learn some HTML and put the following up.

Pages:

  1. Company home page.

    Has details about what the company does and pictures of the product.

  2. Company “About” page.

    Make sure you list your companies phone number (even if it is to your cell phone), email address, physical or mailing address. You can put a little something about your company, to add some more content.

  3. Product Page.

    Lists your services or products, if possible. Make sure you list details about the service or product. The more details the better the customer will be able to compare and decide which product is best.

    You want people to understand what all your product has, does, and why they should buy it. If you say, “Buy this product because I make it and it is awesome!” I would wager a guess that barely anyone is going to, unless they have a lot of trust in you.

  4. Feedback.

    When you get feedback, list it on the site. A person may or may not take it with a grain of salt.

There you have it, four pages, that require minimal amount of work and updating. If you can, it might be better to split multiple products or have a summary of your products on the “Product” page and then have separate pages that have more details.

Start with an Auction Site

It is better to test your product as you create them in your own time on an Auction site that only requires you pay a fee when you sell a product. That in opposed to a service that requires you pay a monthly rate regardless of whether you sell anything or not.

You will always have to pay a small fee for credit transactions, but if you get big enough to open a merchant account, then you’re probably making enough to pay the fee for that merchant account to get the smaller fee.

The auction sites get out of your purchase is a fixed rate and a small percentage of the full price. Yes, it is terrible. When you only sell a few products a month, it isn’t that bad. When it does get bad, is when you sell a lot of products, then the expense isn’t worth it.

When you outgrow the Auction Sites

When you do start selling enough products, the next step should be to find a hosting account where you can pay a small price for hosting (doesn’t have to be dedicated) that will give you access to running an online store.

If you don’t wish to or don’t know how to run a hosted site, then a service like StoresOnline is something that you are looking for. You already know that your product sells well and know what you can afford and what your production is.

Here are some alternatives to StoresOnline that you have, in order for you to make the best choice.

  • Yahoo! Small Business

    The prices are many times less than StoresOnline.

  • Price Grabber

    Price Grabber is where I find most of the products that I want, that isn’t books. If you sell electronics or other merchandise that is also found on the site, you can be listed along site others. The best part that I find, is that there are reviews and ratings. If I find a lower price on one of the “trusted” small business sites, I’ll be more likely to choose them.

    Also, what you can factor in, are hard to find or rare products that a few people or no one else has. If you have that product more people will be willing to give you a try.

    The hardest part will be gaining trust, but once you are “in” then you’ll find more people come knocking at your door. There are quite a few sites that I have a lot of faith in. You could too be one of those sites. Well, it might take a year to get there, but okay.

These are a few, there are others. Just do your research and find one that you like. If you decide that none of these fit in to the level of which you do business, then you can afford to hire web developers and people who know what they are doing in IT to do everything you need to run an online business.

Businesses Fail

It is a fact. A large percentages of new businesses will fail, that is also a fact. If you want your business to succeed, you will have to put in the effort and money (however small or large you can afford) to push it along.

If it was me and I have planned on developing a small business before, then I wouldn’t want to spend more money than I had to.

Notes

[1] Links were purposely left out to keep from advertising the sites. I believe everyone knows or can find the sources if they want.

Disclaimer

This is largely my opinion to express the importance of doing research and not just jumping head first without looking at all of your options. You don’t have to take my formulated opinion based on what I’ve read, experienced, and done. I want you to form your own decision and whether that is StoresOnline, Yahoo!, eBay, Amazon, or Price Grabber, then I’m all for what empowers you.

I have no vested interest in StoresOnline, Yahoo!, eBay, Amazon, or Price Grabber. I gain nothing and lose nothing by whatever decision you make.

Possibly Related Posts:


Confession: I don’t go through Akismet Spam and mark as ham

Posted by Jacob Santos on December 3, 2007 Comments Off

I don’t make time to get the one or two people that may have submitted a comment that was caught by the spam filter when it wasn’t spam. I do check, but when you have 300 spam comments, and pick up another almost within minutes of clearing out the spam. It can get tedious quickly.

I do like people commenting on my blog, but do realize that I don’t want to spend any long amount of my day filtering the spam from the ham. Although, I do plan on going back through all of my blog comments that passed through and rechecking them for spam. There were times when I got too many legitimate comments that one or two spam comments were pushed down before I could catch them.

I also closed the comments of old blog posts that won’t receive any legitimate comments anyway, because usually they are the ones that get the most spam comments. It appears that some spammers believe that this a forum based on the title of several blog posts that I made several years ago in a failed (never even tried) attempt to create a new forum.

I might have plans on going back and closing other blog posts while I’m at it. However, with school projects and such, I’m not certain that I’ll be able to get to it this week.

Possibly Related Posts: