PHP Components: Shipping Documentation With Your Component
In my Beyond Frameworks talk, I explained how a component-based architecture can help answer some of the important (i.e. expensive!) questions you might face when creating long-lived apps that rely on a PHP framework. In this series of blog posts, I'm going to look at how to go about creating and working with components.
I'm now going under the bonnet of our components, and looking at the different file roles that the PEAR installer expects to find when we distribute our component as a PEAR-compatible package. Documentation is very important to your users, but what you ship in your PEAR-compatible package should really be just the bare minimum.
Documentation Is The Missing Feature
I'm sorry to report that there is currently a large gap when it comes to handling of documentation in PHP's PEAR-driven packaged ecosystem.
- There is no standard markup format(s) for documentation shipped in packages.
- There is no standard structure to install a package's documentation into.
- The PEAR installer does not gather up all of the installed documentation to generate a single PHP Manual-style local website of all of the installed PEAR-compatible packages. This would be a killer feature for someone to create.
- The PEAR installer does not auto-generate PHPdoc-compatible documentation from all of the installed PEAR-compatible packages after installation.
The pear.php.net website hosts documentation for the PEAR project, but at the time of writing this documentation isn't shipped with PEAR (or PEAR-compatible) packages.
During the rehersals for my Beyond Frameworks talk, my test audience was crystal clear about the importance of documentation. The PHP Manual is undoubtedly one of PHP's killer features, and it rightly sets a high standard for the documentation that developers should expect to both create and have provided to them. The process and toolset for documenting PEAR-compatible packages isn't yet a mature practice, and there's definitely an opportunity for someone to step up and plug this gap.
This doesn't mean that it's a waste of time documenting your packages; it just means that, today, you're better off including some documentation in your package, and publishing the rest of the docs somewhere else.
What Are The Docs You Should Include In Your Package?
Every PHP component should, as a minimum, ship the following documentation inside the PEAR-compatible package:
- LICENSE.txt - what copyright and licensing terms apply to the package
- README.txt - general information about the package, and where to find the package's main website
The LICENSE.txt file is absolutely essential: it tells responsible developers whether or not they can legally use your work in their project, and just as important it sets the scene for whether or not anyone can fork your component should you decide not to maintain it any more. This file should contain the full text of the license. If you are not sure which license to use, the PHP ecosystem strongly prefers the new BSD license or the MIT license.
(You should also include license details in your docblocks at the top of your source files; that is a topic for later in the series).
The README.txt file is also essential: at the very least, it tells developers where to go to find your component's website and full documentation. If you publish your source code via GitHub, you can write this file as README.md (using GitHub's flavour of Markdown) and GitHub will automatically pick up the file and display it on your repository's homepage (as an example, see phix's homepage).
Quite a few existing PHP components also include a CREDITS.txt file, although some PHP components prefer to publish this information on their website instead.
Where Do Docs Go Inside Your Component's Structure?
If we look at the ComponentManagerPhpLibrary component, you'll find that the essential documentation files actually live in the component's top-level folder:
Truncated by Planet PHP, read more at the original (another 2711 bytes)