Code Craftsmanship

Dunedin now has a local code craftsmanship group!

Code craftsmanship is like craftsmanship in any other area. It describes the transition between knowing how to write code, and knowing how to write good code. Like most crafts, there's an element of constant iterative learning involved. Working with people who have more experience than you can save you some of those iterations.

This is an excellent opportunity to meet other programmers, and discover the rich, yet hidden IT talents in Dunedin. If you're interested in joining us, check out the (brand new, as yet unfinished) website.

Project Documentation

Why is it that most open source project pages are so terrible at documenting their own project?

I'm not talking about API or technical documentation - I'm talking about telling new visitors to your site what the hell your code is about.

Project authors, here are some handy tips:

1. On your project front page, right at the top, put a simple explanation of what your code does (or what you hope it will do someday). Remember that your audience may not have the same level of technical experience as you do. Examples (screenshots, code snippets) are a MUST. A picture speaks a thousand words and all that...
   
   
2. Make sure you include the development status of your project. I can't count the number of times I've spent 30 minutes looking at a project only to realize that it's not nearly complete enough to be usable to me. There's no shame in saying "this library is working, but not production ready. It is missing features X, Y, Z"
   
   
3. Inject some enthusiasm! How many boring, dull, dry project descriptions do I have to read through? Most sound like the authors aren't passionate about their product. Sell your project; inject some enthusiasm, and maybe your viewers will become more enthusiastic in the process!

Well, that's my rant for the day. Now I must go update my project documentation...