Contributing to the PHP manual - an introduction

Nov 08 2009

There are many ways to contribute to the PHP programming language. You can contribute by writing code, reporting bugs, helping other users on the mailing lists, writing documentation etc. This article is a guide to start documenting for PHP. I think that one of the reasons that PHP is so widely used is because of the quality and completeness of the PHP manual.

The documentation team can't keep up with the code that is being written for PHP, so a lot of functionality that is available in PHP (or its extensions) is still undocumented. This is especially true for functions and modules that were added to PHP in the last couple of years. I think that it is important to create proper documentation, because otherwise the new functionality will only be used by experienced PHP developers that are aware of the existence of the undocumented functionality.

How to start?

To start writing documentation you should think about what PHP functions, classes or extensions that you want to write documentation for. I think one can have several motives to start writing documentation for PHP. This list might help you decide what you want to document about, but is by no means complete.

  • You've used an extension in PHP that you've gotten pretty familiar with, but the documentation of this extension is incomplete.
  • You've encountered one or more bugs in the current documentation that you want to correct.
  • You want to contribute to PHP because you use PHP a lot, but you are not comfortable with programming in C. In this case the pages undocumented functions in the PHP manual or missing examples in the PHP manual are a good place to start.

After you've decided what you want to document, it's time to read the PHP documentation howto. This howto is not a definitive guide to start writing documentation for PHP, but it should be sufficient to get you started. The documentation team has switched to SVN a few months ago so there might be some references to CVS in the howto.

After you've read the basic principles of the PHP documentation process, you can introduce yourself on the phpdoc mailinglist and start submitting patches to this list.

Karma

You need to earn some karma before you will receive direct write access to the phpdoc SVN Repository. To earn karma you can join the discussions on the phpdoc mailinglist and start submitting patches to the documentation on the list. After you've earned some karma you can apply for a SVN account.

Translating the manual

The PHP manual is available in many different languages. If you're not a developer, you can still contribute to the PHP documentation by translating the manual into your own language. You can start by posting a message to the phpdoc mailinglist in which you introduce yourself. It is also possible to subscribe yourself to a language specific mailing list. All documentation related mailing lists start with "php.doc.", you can view the available lists at news.php.net. Additional information can be found in the PHP wiki item "Working with translations".

What you should know about the PHP Manual

Note that this information can also be found in the PHP wiki and elsewhere on the net, but I thought it could be useful to summarize it here.

  • The PHP manual is written in docbook XML format with a few enhancements that are PHP manual specific.
  • The PHP documentation source resides in the "phpdoc" SVN module from the PHP SVN Repository.
  • PhD is the PHP tool that converts the docbook xml files to the various output formats of the PHP manual (currently PHP, HTML, PDF, CHM and man pages can be generated). Information about using PhD on windows can be found in an excellent blog post called "Setting up PhD on Windows" by Elizabeth Marie Smith.
  • The PHP manual is generated on a weekly base. The version that's used by the documentation team is updated four times a day and can be found at http://docs.php.net/.
  • If you happen to work for a hosting provider, you can help the PHP Community by mirroring the PHP Manual for your country.