Your SlideShare is downloading. ×
Best Practices: Documentation
Upcoming SlideShare
Loading in...5

Thanks for flagging this SlideShare!

Oops! An error has occurred.


Introducing the official SlideShare app

Stunning, full-screen experience for iPhone and Android

Text the download link to your phone

Standard text messaging rates apply

Best Practices: Documentation


Published 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.

Published in: Technology

  • 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