Best Practices: Documentation

Uploaded on

Third in a series of presentations on PHP Best Practices for the Burlington, VT PHP Users Group; this segment covers Documentation, both API and end-user.

Third in a series of presentations on PHP Best Practices for the Burlington, VT PHP Users Group; this segment covers Documentation, both API and end-user.

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
No Downloads


Total Views
On Slideshare
From Embeds
Number of Embeds



Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

    No notes for slide


  • 1.
      • PHP Developer Best Practices Burlington, VT PHP UG
      • 26 June 2008
    Matthew Weier O'Phinney Software Architect Zend Technologies, Ltd.
  • 2. About You
    • Can you read your own code? Can others?
    • Is your software tested?
    • Is your software documented?
    • Are you using source control?
    • Does your team work efficiently?
    • Do you push buggy software into production?
    • Do you have a deployment plan? Does it include contingencies for rollbacks?
  • 3. What we'll cover tonight Documentation
  • 4. But we don't have time!
    • You don't have time to code?
  • 5. API Documentation is Easy
    • Simply prepend PHP docblocks to your methods and classes; your IDE will often do it for you:
  • 6. What can I document this way?
    • Classes, methods, class properties...
    • Use annotation tags in source comments to provide context: @param, @return, @throws, @see, @todo
  • 7. Docblocks can organize code
    • Utilize @category, @package, @subpackage; phpDoc uses these to organize documentation.
    • Prefix your classes; easier to browse, and easier to mix with other libraries.
  • 8. Docblocks can organize code
    • Utilize @todo to keep track of what still needs to be done!
  • 9. Generate pretty API docs
    • phpDocumentor:
    • Doxygen:
  • 10. See?
  • 11. Caveat
    • Be careful what you say:
      • Docblocks can go out of date. Be general, except when it comes to the parameters and return values.
      • When in doubt, unit tests don't lie.
  • 12. IDEs like DocBlocks, too!
    • IDEs introspect DocBlocks to provide typehinting, return values, and method descriptions.
  • 13. So does Zend Framework!
    • Various Server classes utilize DocBlocks to provide hinting for parameter and return value types, as well as method descriptions
      • Zend_XmlRpc_Server
      • Zend_Rest_Server
      • Zend_Json_Server (coming soon!)
      • Zend_Soap_Wsdl (coming soon!)
      • Zend_Tool (coming soon!)
  • 14. End-User Documentation
  • 15. Users like documentation, too
    • End users like to know how to use your code and applications
    • Give them a manual!
  • 16. XML is not a four-letter word
    • DocBook is the most common format for open source documentation
    • DocBook can be compiled to a variety of formats: HTML, Windows Help files (CHM), PDF, and more.
    • Often used by book publishers (O'Reilly)
    • It powers the manual
    • It powers Zend Framework's manual
  • 17. DocBook is easy
  • 18. One possible rendition:
  • 19. Summary
    • Document your APIs as you code them
      • Run phpDocumentor frequently to keep the API documentation up-to-date
    • Write end-user documentation
      • Use DocBook to allow for multiple formats