First, don't be worried about learning another language or syntax because DocBook is fairly straight forward and most contributors simply cut-n-paste existing files, modify the content, then commit. It's just plain text.

The following is a quote from DocBook: The Definitive Guide:

DocBook is a very popular set of tags for describing books, articles, and other prose documents, particularly technical documentation. DocBook is defined using the native DTD syntax of SGML and XML. Like HTML, DocBook is an example of a markup language defined in SGML/XML.

Simply this means that writing a DocBook file is no more than writing a text file and using a few simple “tags” when needed. Like HTML, an opening tag is a < bracket followed by the tag's name, optionally some arguments, and then the > bracket (e.g. <para> for paragraphs). A closing tag is a < bracket followed by a / sign, the tag name, then the closing > bracket (e.g. </para> for paragraphs). For example uses, have a look at an existing file within the PHP manual sources, or use the documentation skeletons.

As described above, DocBook uses a similar structure to HTML with the main difference being DocBook uses tags to define the meaning whereas HTML often times defines the look and layout. So the idea behind DocBook is to define as much as possible about the information so that build and rendering software will intelligently output the text into many formats.

We use DocBook because it makes it easy to generate several formats of our documents (HTML, PDF, Microsoft HTML Help (CHM), RTF, etc.), and DocBook is the standard way for storing structured technical information.

DocBook version upgrade history: On January 2, 2007 we upgraded from DocBook 4.1.2 to 4.5 and then to DocBook 5 at around June 20, 2007. These upgrades included changes to most files in the phpdoc CVS repository.

For information about the DocBook DTD, look here: http://www.oasis-open.org/docbook/.

There is a DTD reference for DocBook at: http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html.

Get Going With DocBook, Notes for Hackers: http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html.

You can also find more information and downloads of style sheets and other tools for DocBook in the DocBook Open Repository at: http://docbook.sourceforge.net/.

You can also read the book DocBook: The Definitive Guide online, or buy it at a bookstore, but be warned, that the first edition of the book (currently the only printed edition available) contains outdated information.

There is a great DocBook Wiki, where you can collect information on DocBook editors, transformation tools, etc.