Good Error Reporting

One thing most developers hate is dealing with users' error reports. It's not that the users are evil, it just happens that no one has a good solution for communicating what are the results of an error or the conditions that lead up to one.

This is a subclass of the larger problem of communicating software concepts. It's not too dissimilar to the problem of conveying a feature request, walking through a use case, or an experiment proposal. But for now, I'll just stay with the question of error reports.

It seems to me that what might be lacking is the visual component to an explanation. Whenever I have to solve someone else's software problem, I need to see what went wrong. But, this is not convenient when the user is not in the same room. As I'm getting ready to send some simulations that require some setup to a lab on the other side of the Atlantic, I've come to realise that I need a solution to this. I think there may be two practical solutions that could work well on top of the usual collection of core and log files.

Use a remote assistance application. This is fine if you have a lot of bandwidth and are in similar time zones, and you actually know how to use one of these applications. Time coordination and expertise are required.

Use a screen capture program and create a movie of the problem. This has the advantage of being simple to do and it provides a record of the incident for future reference. Given that there are few fairly easy to use screen capture applications (such as Camtasia), this makes for a strategy that should be easy enough for a client or colleague to implement.

Personally, I think video is an underused communication tool. Video is getting easier to handle, be it as real time conferencing, capturing incidents or presentations. It is a communication and collaboration technique that merits further exploration.

The Disaster of Unplanned Collaboration

I just witnessed an organisational disaster. One of the other research groups ordered a very large, very heavy table. The table is 2 x 1.5 m and 400 kg; apparently it's part of a very expensive microscope.

In a disappointingly predictable fashion, there was no plan to bring this table into the building. The delivery truck nor the building staff had had furnished moving equipment. There is no ground floor entrance to the building; there was no plan to bring it up the stairs, no appropriate moving equipment and no one supervising to prevent damage to the new equipment or injury to those moving it. The person responsible for the order simply rounded up the available men and asked them to carry it in.

This is the most astounding bit of stupidity and organisational incompetence that I've seen in a long, long time. I found out after that the reason there was no plan was because the person who bought the table did not want to pay the extra 400€ to have it installed. Granted, that's an expensive installation, but given that this is part of a very expensive piece of lab equipment (worth many thousands of Euros), it seems to me that the installation cost would be well worth its value as insurance. Had the table been broken or someone injured, the cost would far outstrip the 400€. In fact, wasting forty minutes of the fifteen people gathered up from around the building probably cost more than 400€.

Thankfully, nothing went horribly wrong and the table did get into the building, though this is purely by luck.

All that was needed was a little planning. We needed the proper moving equipment and direction. Considering that this a site with many labs, with many large, heavy pieces of equipment, there would be some readily available resources for moving and installing equipment. But, apparently there isn't, or, the person responsible for purchasing the table was simply to much of an imbecile to ask for such resources in the first place.

We Need More Tools to Play Nicely Together

I just finished installing Google Desktop 4.5. This is my second try with Google Desktop, I tried it last spring and was disappointed with the performance. However, the performance issues seem to be solved with the latest version.

One thing that it does very nicely is to index my conversations (emails and chats) from GMail and GTalk. This is brilliant. One of the corner stones of good collaboration is good communication, and this helps me work with my previous communications. But, why doesn't Google Desktop work with my on-line files? I have my bibliography at CiteULike, documents and spreadsheets over at Google Docs, bookmarks at del.icio.us, photos at Flickr, movies at YouTube. Shouldn't I be able to index these too?

I think there is an incredible integration of tools that could be done through Google Desktop. I should be able to search for a keyword in my research, something like "biomechanics" or "L-systems", and get back my relevant research notes (from Google Docs), bibliography (from CiteULike), and correspondences (from GMail), all of which exist on line, along side my simulation results on my hard drive.

Additionally, a social layer could be added. If I could index my items online, I could also index my friends' and colleagues' publicly available items too.

And if anyone out there knows of tools to start this integration, please, let me know!

The Importance of Code Formatting

I'm currently working through the mess of code. It's not fun. The code is poorly written. It has no consistency in the spacing, variable names, comment style, or name conventions. There's whole pages of dead code and comments attached to nothing.

How did the code end up this way? As far as I can tell, I am the fifth or sixth person to work on this code base. Naturally, there's a small amount of dissimilarity in styles to be expected. That's a speedbump in productivity, but no big deal. But, the person before me to work on the code clearly had no idea what he was doing. The formatting of this code is all over the place. And now, the consequence is that the code is difficult to read and understand. I've discovered several bugs that are due to extra and missing brackets. From bad names and extreaneous comments, the only way to figure out how parts of the program work is to step through line by line and deduce the logic. All of that adds up to a lot of wasted time on my part.

So, how does one evade this problem? I believe that there are two solutions that are needed.

Firstly, there is a need for better tools to do code formatting. Everytime code is checked in to a repository, in must be beautified. Unfortunately, I have yet to find a tool that does a satisfactory job. But there are a few candidates that may work after a few feature additions.

Secondly, a code and documentation style guide should be used. Had I insisted on the use of a style guide early in the project, a good chunk of this mess could have been avoided. And, a printed version of a guide is handy too. When a programmer stops following it, it can be rolled up and smacked accross his nose.

I need to do more work on both these items before they can be put into practice. Hopefully, I'll come up with something that can make my future collaborative programming a saner experience.

Nature is Opening Up the Peer Review Process

The venerable journal, Nature, is running a trial on opening up the peer review process. The process appears to be quite simple. First, go to the peer review page, scroll down and follow the trial peer review link. Once there, you can see the list of papers up for review, download, read and post comments to the website.

There is still the usual anonymous jury reviews for these papers. That part of the process is still vital. The open comments are an additional check on the content of these papers. By opening up the review process, there is much less chance of error or omissions in the publications. After all, it is not possible to always know who has the most pertinent background knowledge to review a particular paper, and sometimes, the jury reviews can have errors too.

This is a trial project, but I think it has some terrific implications. So, if you have any expertise in the papers currently for review, go and comment on them.

Tick

I've realised that I really should be doing some sort of time tracking to figure out how well I'm using my time. I'd like to know how much I'm spending in productive work compared the work time wasted to tinkering about, spending time in meetings and blogging.

After a quick search, I've settled on using Tick. I've been tinkering around with Tick for a couple days now, and I think it fits almost right into what I need.

Pros:

• Simple, easy to use
• Integrates with Basecamp
• Clear, simple reports
• Supports several users - track time of your whole team
  

Cons:

• The non-free features, like Basecamp integration, are a bit pricey. 9$US a month is expensive for just a time-tracker. I'm not sure I'll keep with it after my free preview is finished for this reason.
  
• The Basecamp integration does not import milestones and to-do items, which are exactly the items I want to keep track time on.
• Adding new tasks to a project requires jumping through a few pages. It would be much better to be able to create tasks on the Time Card page.

Overall, it's a good product, and worth keeping tabs on. However, I'm not convinced that it is yet the killer app for time-tracking. The biggest sticking point is the price. I'm not saying it should be free, but the 9$US a month for the basic package is a bit steep. Especially to those of us that can't file it as a business expense and get reimbursed.

Idea Notes

Here's an item for the wishlist.

What I need is a good way to put together notes on ideas and initial sources that I have regarding nascent research projects. It needs to be a notebook, whiteboard & citation manager, orgranised by topics.

This sort of tool would let me create everything from back-of-the-napkin sketches to literature reviews to full-blown research proposals. When a project moves into the real work and research, then other tools would be appropriate.

I havn't found a tool that lets me do this nicely yet, though I haven't done any real inquiries into this idea either.

Maintaining Good Collaborative Practices

It's difficult to introduce a tool into another's work habits. And, as I've come to realise, it's much harder to keep a tool in another's work habits.

This point has left me with a bit of a conundrum lately. There are a number of tools that offer collaborative features that have been very useful to me lately. However, I've been running into the very large stumbling block that it's has been very difficult to keep my colleagues that are working on the same project using these tools.

Particularly, I've been extensively using Basecamp, Writely & CiteULike. These have all become indispensable tools in my work. However, it is becoming increasingly difficult to keep the data contained in these tools up-to-date as my colleagues have been inconsistent in their usage of these tools.

I do save time by using these tools; I waste time because others are not using these tools. I'm not sure if on the balance I've gained something.

What to do?

Vitaly Friedman's Notebook: List of nifty tools for drawing diagrams, charts and flow-charts

Vitaly Friedman's Notebook: List of nifty tools for drawing diagrams, charts and flow-charts

That article contains a nice list of tools for the creation of charts and diagrams, items that are often needed in scientific writing. Some allow for collaboration and some not. I'll need to take a thorough investigation of the tools on this list to see how they stack up. Future posts will probably follow with some analyses.

Gliffy.com - Create and share diagrams online.

Gliffy.com - Create and share diagrams online.

Gliffy is nice, simple, online tool for creating diagrams and, like so many tools do now, it allows for collaboration. I think this fills in a small gap in the collaborative tools gamut needed for writing documents.

Now, if we add in a charting & graphing tool, that could take data from a Google Spreadsheet, and a vector drawing tool and mash all these together with Writely, we would have a great online, collaborative solution for writing scientific documents.