Best Practices – Part 2

I just got out of Matthew and Lorna's tutorial on Best Practices and my mind is swimming with all of the things I want to try.  So, pretty much a normal day for me.  Part 1 can be found in the related links on the right hand side.

Part 2 is basically more of the same; a list of all the things you're not doing but probably should.

Let's start with documentation.

End User Documentation

The purpose of end user documentation is to provide a narrative for developers.  In other words, the purpose of providing end user documentation is what is demonstrating how to interface with the software you are writing.  It will often describe architecture, theory and design patterns that you used to implement various parts of your software.  Even though documentation is a very important part of the overall process it is often one that is not often properly done.  Or even partially done.  Part of that might be due to the fact that deciding on the tools to use can be a difficult decision to make.  So here are a few options that you have

Wikis

If you don't know what a Wiki is by now you're probably been under a rock for the past 10 years.  The basic concept of a Wiki is that it is a community forum where people can edit information.  It is generally easy for others to contribute but is generally un-distributable.  Meaning that besides the HTML interface of the rendered Wiki code you don't really have any ways of distributing it in an alternate format such as PDF or CHM.  Other problems are that it is difficult to translate, since it is fairly free-form and it is usually unversioned.

HTML

We may not often think of straight HTML as a documentation format but it can be.  It is easy for people with any web background and can be distributed but is difficult to offer in other formats such as PDF and CHM.  Since it's more structured than a Wiki it can be translated but will run into several of the same problems.

Docbook XML

Docbook was the favorite.  This was easy to say because Matthew said "It's my favorite".  If you are familiar with XML you are already familiar with Docbook, though there are some specific tags and attributes that you need to use.  I found some information on Docbook Stylesheets that might be interesting to highlight some of those.  Some of the benefits of Docbook are that it is reasonably easy to understand and because Docbook is really just an intermediate language you can use it as the glue between various documention formats.  Because it is in a highly structured format it can be both easily translated and it also supports versioning.  One thing to note is that because code can mess up the XML format that most of your code examples should most likely be written within CDATA tags.

The thing to note is that most people can't read XML directly, so you need to render it in the format.  One of the options you have is the PHP Docbook renderer.

Additional documentation

Documentation doesn't necessarily mean "documentation".  Documentation can be a myriad of other things.  It can be

• Tutorials
• Installation instructions
• Examples
• FAQs
• Forums
• User contributed

Lorna said something interesting that I thought was pretty important.  "If you don't know where to get started with an open source project, work on examples."  In other words you know the software, but you don't want to break something so you're unsure as to where to start.  Want to know where to start?  Examples.  There you go.

Be a User-Contributor

• Answer forum questions
• You don't need to be an expert
• Hang out on the IRC channel
• Help wirth project docs
• Blog
• Don't think of yourself as a consumer

The one here that I found the most interesting was that you don't need to be an expert.  Talking to the "experts" can be a little daunting.  They're the experts!  No they're not!  My definition of an expert is someone who knows enough to know they're not an expert. 

Testing

Why test?

• Makes future maintenance of the code easier
• Defined expectations
• Test known behaviors
• Identify early when changes in code break existing behaviors
• Quantify the quality of your code
• Code Coverage (not the best metric, doesn't tell the quality of the test)
• Self-documented behaviors via unit tests

What is not testing?

• Reloading – In other words, hitting F5
• Var_dump()

What is testing?

• Reproducible
• Automatable

Test Driven Development

Test driven development is a methodology that I have become a recent convert to… big time.  Every customer I have talked to about it has become believers in test driven development.  Zend Framework uses test driven development.  I won't go into how to do it, though I did do a video on it that you can check out.

A couple of things to note about test driven development.

• Write code to make the tests pass
• Allows for playing with the API's before you've committed to coding them
• Often hard to get into the rhythm; once you do it's hard to quite

I would like to spend more time on the subject but that's all I have time for.

Conclusion

I was hoping to end this with part 2 but there's still a lot to cover (Matthew and Lorna had a lot of information).  So I will work later on to finish up with part 3.