Best Practices: Documentation
Upcoming SlideShare
Loading in...5

Best Practices: Documentation



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.



Total Views
Views on SlideShare
Embed Views



2 Embeds 13 8 5



Upload Details

Uploaded via as OpenOffice

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
Post Comment
Edit your comment

Best Practices: Documentation Best Practices: Documentation Presentation Transcript

      • PHP Developer Best Practices Burlington, VT PHP UG
      • 26 June 2008
    Matthew Weier O'Phinney Software Architect Zend Technologies, Ltd.
  • 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?
  • What we'll cover tonight Documentation
  • But we don't have time!
    • You don't have time to code?
  • API Documentation is Easy
    • Simply prepend PHP docblocks to your methods and classes; your IDE will often do it for you:
  • What can I document this way?
    • Classes, methods, class properties...
    • Use annotation tags in source comments to provide context: @param, @return, @throws, @see, @todo
  • 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.
  • Docblocks can organize code
    • Utilize @todo to keep track of what still needs to be done!
  • Generate pretty API docs
    • phpDocumentor:
    • Doxygen:
  • See?
  • 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.
  • IDEs like DocBlocks, too!
    • IDEs introspect DocBlocks to provide typehinting, return values, and method descriptions.
  • 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!)
  • End-User Documentation
  • Users like documentation, too
    • End users like to know how to use your code and applications
    • Give them a manual!
  • 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
  • DocBook is easy
  • One possible rendition:
  • 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