Sunday, January 28, 2007
Sunday, January 21, 2007
Runtime Chosen Library
How Not to Use Inheritance
Inheritance is Just a Tool
Sunday, January 14, 2007
Currently I am using Ruby on Rails for a Data Analysis project. Rails has a standard directory structure which you are supposed to follow. This includes support for separate development and production databases. It seems like what I want to do is check in this entire directory structure and then have one checkout for each developer working on the project and another checkout for the production release.
Here are my problems with this. First, it feels wrong to check passwords into revision control. This just doesn't feel very secure. Second, configuration information can change without the project changing. Mary is using database A for her developing and I am using database B for my developing. If every time Mary does an update she gets my database configurations along with my code changes, either she'll be annoyed because she has to update her config file, or I will be because she didn't and she changes my instance of the database unexpectedly.
Don't check in config filesSo the obvious thing to do is to not check in the configuration files, but there are problems with this too. When Sue gets added to Mary's and my project, she can't just check out the repository and be up and running. She needs to create all of the config files that are missing. I guess this can be part of the same documentation that includes where the repository lives, but this still seems inelegant to me. A bigger issue is deployment. When DataAnalysis version 2.1 is deployed and on Saturday night the server running it has a disk crash it would be great if Dave, who's on call and not involved with the project, could restore DataAnalysis without having to call a developer (particularly me). We, of course, have tagged the project in subversion and there is documentation telling Dave how and where to check out the tagged version, but what about the config file? If he has to actually edit a config file of an inhouse developed application, he may be tempted to call me up just to make sure it is done right. It's bad enough Dave's Saturday night was disrupted, why should mine be? How can we make deployment one step? (Rule 2 of Joel's 12 steps)
OK, so I've rambled long enough. How do you deal with this scenario? Please leave a comment and let me know, I'd love to hear it.
Thursday, January 11, 2007
And yes, I am playing around with things that I can do to avoid the "walls of text" that I previously mentioned. Please bear with my experimentation.
Wednesday, January 3, 2007
Have you ever had the experience where a user/boss/coworker asks, "How do you do X?" and you answer, "It's explained in that document I sent you." and are met with, "Oh, I haven't read that yet" or "I just skimmed that". While it gives us great stories about the incompetence of our users/bosses/coworkers, it is frustrating and not productive. Here are some thoughts I try to keep in mind when writing to reduce these occurrences:
- Know and target your audience
- Use the inverted pyramid
- Be concise
- Hyperlink rather than give details
- Avoid “walls of text”
Just as the best diet is the one you stick with, the best style of writing is the one that is read. Therefore, except for reference material, when choosing between readability and completeness, choose readability. Most of our writing should probably look like we are writing for the web.
So what are other keys to making writing readable? What should I be doing to make my blog more readable?