Project release

Something to care about when releasing open source project to the public.
How to make it visible?

Every project solves a problem and the first thing people would like to know is not a coolness degree of the project, but where the problem is. There are of course professionals who do not need anything to explain, but for major part of an audience this might be an issue. Why would you care? Perhaps because people might not be interested in your project right now, but they (or their colleagues) can stumble upon the same problem in future and they will have better chances to remember your project if you will interest them enough.

Try to figure out what assumptions your end-users might not have about the problem (they may not realize that this is a problem that needs solving). If possible, explain the problem in terms that even a beginning programmer could understand. Consider your audience though.

Next, how does the package/project uniquely solve the problem? This is something that most documentation lacks. For example, there are many template engines. All of them solve the same problem, but none of them do it in the same way. A block-based template engine does not have any logic at all, whereas a template like Smarty defines a whole new template language. Some template engines compile their templates, others don't. What is unique about your package? Can someone who has never seen the code get a good idea of how does it solve the problem?

In the end (and this is rather obvious) every publicly accessible aspect of the package must be thoroughly documented. If your package/project is a re-usable class, document every method that users should expect to use. If your package has public constants, document their meaning and where they should be used. Document any interfaces that users must use, such as a database DSN, command-line arguments for applications, configuration file contents, or any other non-code elements.

Include at least 2 code examples: one simple and one complex. This is obvious, but projects and packages are designed to be used - show your users how to use them! :) An ideal approach would be to provide a CookBook with recipes for intended meaning and not just testcases, so that users can contribute some.

At last, proofread your documentation. If possible, have someone else who is not as familiar with your project take a look at the documentation. They will catch assumptions that you have missed. This is probably the most important step - to get a test look from outside.