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
Slideshare-icon 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