Archive for the ‘tools’ Category

Making developer docs more accessible

Thursday, January 8th, 2009
Java EE - crxdeploy/build.xml - Eclipse SDK - /Users/sethgottlieb/Documents/projects/clients/time_interactive/development/crx-clean-ab
Uploaded with plasq’s Skitch!

What do developers hate more than writing documentation? Writing documentation that nobody will read. I think everyone has been in a meeting and heard someone complain about needing some information that they didn’t even bother to search the wiki or document repository for. But what if the documentation was already in the developers face?

New
Uploaded with plasq’s Skitch!

A few weeks ago, a client turned me onto “Cheat Sheets” in Eclipse. Those are the little instructions that appear on the right-most frame of the Eclipse IDE. You may have used one of these Cheat Sheets before (and not known what they were called) but you probably didn’t know how easy they are to create. Simply choose the “File | New | Other” menu option and then, under “User Assistance,” select Cheat Sheet. This will give you a simple editing tool to create step by step instructions. The underlying XML is very simple so you can also just use Eclipse XML editor if you want to.

Java EE - crxdeploy/testing.xml - Eclipse SDK - /Users/sethgottlieb/Documents/projects/clients/time_interactive/development/crx-clean-ab
Uploaded with plasq’s Skitch!

This form of documentation is best for things like development environment setup. It is not so great for API or architectural documentation. It assumes that the developer is using Eclipse and has been able to check the appropriate source tree out of the source code repository because the documentation is stored within the project. I would use this in conjunction with a README and INSTALL file. README would be used for information about the application (version, usage, recent changes, open issues). INSTALL would be for someone installing the compiled application. The Cheat Sheet(s) would be for developers that are getting their Eclipse environment together.

Is anyone else using this feature? If so, have you found it effective?

Improving your blog’s accessibility

Wednesday, January 7th, 2009
DoingMedia blog
Uploaded with plasq’s Skitch!

Todd O’Neill, over at DoingMedia has started to embed automatically generated audio versions of his blog posts to make his content more accessible to the visually impaired (and to sighted people whose eyes are busy doing something other than reading – like watching where they are driving/running/walking). He is using a service called Odiogo that takes in an RSS feed, does the audio production, and gives you a play button to embed in your blog template. The audio channel of your feed can also be published to iTunes. Here is how Odiogo works. Best of all the service is free. The plan is to include advertisements in the audio that pay for the service and may lead to a revenue share among participating bloggers.

Cool stuff Todd!

Things now at 1.0 (plus a discount)

Tuesday, January 6th, 2009
Things
Uploaded with plasq’s Skitch!

One of my favorite personal software applications is Things by Cultured Code. I wrote about Things a while ago in a long post of Mac applications that I like. Since that time I have increased my usage of Things. It is now everything from a to do list to a personal issue tracker for projects that I work alone on. Being able to quickly jot down a task saves you from breaking the flow of what you are currently working on. The iPhone application is there to receive tasks when I am not near a computer. The two applications synchronize whenever they see each other on a WiFi network.

The Cultured Code Team has just released version 1.0 of Things. The beta releases have been free but now it costs $50 ($49.95 to be precise). If you are also hooked on Things, you can use the coupon code “THINGSPRESALE20″ to get 20% off the list price.

Watch Out Webex

Tuesday, June 24th, 2008
Skitch
Uploaded with plasq’s Skitch!

I just got through a 2 hour WebEx session where I walked through my deliverable with my client. At $0.33/minute/person for a pay per use session, the bill probably came to around $120 (without integrated voice). That is actually more than the train ticket to get to New York where the client is. Still, when you factor in the time (9 hours of travel round trip!), parking at train station, and (of course) the carbon, it was an economical choice.

An even more economical choice would have been to use Google Doc’s presentation feature for free. It would have worked for me because I wasn’t showing anything other than slides. If I was demo-ing an application I would have needed to use WebEx or some other real screen sharing application.

Oh well. Something to keep in mind for next time.

Time Machine Restore

Monday, June 23rd, 2008

Although few people do it, restoring from backup is the only way to ensure that your backup and recovery system works. Since upgrading to Leopard, I have been using Time Machine to back up my laptop over the network (onto a and external hard drive connected via USB to my Airport Extreme). What better way to test a restore from Time Machine than to put in a bigger hard drive and restore? I figured if it didn’t work, I would still have my old hard drive (still working but too small).

I am happy to report that the restore went perfectly. The general instructions are to be found here. The only difference is that I restored from the network rather than directly through the USB port. The one little hitch I ran into was that it took a couple of times for the utility to see my new local hard drive.

I am the kind of person who is frequently shocked when things work as advertised so I was in awe that, after I swapped out the hard drive and ran through the process, it was like nothing happened but the free space of my hard drive grew. All the software was as I left it. Even my BASH history was intact. The only thing missing was my “Downloads” – I had to recreate it. I guess this is because Mac regards this as a temporary space and not worth recovering.

So, don’t hesitate to set up Time Machine. It could help you recover from a massive hard drive failure, a stolen laptop, or any other disaster – as if it never happened.

I Use This

Tuesday, June 17th, 2008

I have been on a Mac since I started Content Here a little over a year ago. The migration for me has been an unqualified success. I won’t go back. Here is a list of apps that have made the experience that much more pleasurable.

Mail, Calendar, Address Book: Mac Apps

I decided to go with the Mac defaults: Mail.app, iCal, and Address Book. Since these applications are pretty much always open, I wanted them to be stable, well integrated, lightweight, and just good enough. They work as advertised and I have absolutely no complaints.

Blogging: MarsEdit

When I started taking longer trips for client projects and conferences, I realized I needed an offline blogging tool. For a while I used a simple text editor and then copy paste into the Blogger web UI. Then I went to Ecto which I used for around a month until I got annoyed with its quirky notions about HTML. I bitched a little on the support forums to no effect and then decided to vote with my feet and went over to MarsEdit, which I love. It doesn’t try to give you WYSIWYG editing features and that is OK by me.

Simple Editor: TextMate

I started out with TextWrangler because it’s free. I tried TextMate because I like to be able to set up “projects.” Before I discovered you could set up a “disk browser” in TextWrangler, I fell in like with TextMate. I seem to be in good company because I keep recognizing TextMate in screencasts.

XML: oXygen

I write my reports in XML (DocBook) so a good XML editor that validates as I type and runs my transforms is important to me. I was disappointed to learn that XMetaL doesn’t work on the Mac. I bought oXygen. I first used the Eclipse plugin but then I transfered my license to the stand-alone version, which is a lot faster. I am pretty happy with it. It comes with the Syncro SVN Client which works well enough.

IDE: Eclipse

I rarely do serious coding anymore but when I do, I use Eclipse. Eclipse takes so long to load that it makes me think twice about whether I want to get sucked into my programming head and lose track of time for the next few hours.

Source Control: SVN via Wush and the Syncro SVN Client

Old habits are hard to break and I am a religious source control user for my website and my reports. Wush.net takes care of the Subversion hosting. Syncro is my client when I am not in a command line mood.

Office: iWork

When I bought my Mac, I felt obligated to throw in a license for Microsoft Office. Big mistake. I thought I hated Office for Windows. The Mac version is worse. I am very happy with the iWork applications and tend to write deliverables and presentations in Pages and Keynote and then export to the Microsoft formats. It is a good thing when your office applications don’t suck your will to live. I have NeoOffice installed for the occasional Open Document file I receive. It sure would be nice if iWork would support Open Document. Maybe if both MS Office and iWork supported it, ODF would realize its vision.

Drawing: OmniGraffle

The one Windows application that I thought I was going to miss was Visio. Then I found OmniGraffle and I have moved on. Although there are not as many stencils as Visio, you can read and write from Visio’s XML format with relatively good accuracy.

Image Capture: Command-Shift-4, Flickr, Skitch

For work I look at a lot of software and I take a lot of screenshots. Typically, I use the key command Command-Shift-4, then space to get a .png image of the active program saved to my desktop. Then I upload the files to Flickr and tag them appropriately. After doing that for about a year, I have a nice little library of screenshots that is organized by keyword. When I want to blog a picture immediately I tend to use Plasq software’s Skitch because it lets me quickly post the picture with all my cheeky annotations.

Browser: “CaminoFoxIfari”

I have absolutely no loyalties to any browser and I switch whenever the wind changes direction. Today I am using Firefox 3 because I wanted read my feeds offline with Google Gears. I think I like the Camino keyboard shortcuts the most though. I also like how Safari and Camino share a password database. For some reason I have been leaving Opera out of my rotation. I guess even fickleness has its limits.

Time management: OfficeTime

When you run your own business, you need to be very careful to manage your time efficiently. No one else is going to do it for you. In addition to keeping track of billable hours, I also track time for internal projects including research, reports, conferences, blogging, and general admin. OfficeTime is like a little stopwatch that you can start and stop when you work on different things. There are reports that tell you how you spent your time today, yesterday, this week, last week…. I find that tracking time in this way helps keep me focused on doing the important work and prevents me from task switching inefficiently. OfficeTime is not the prettiest application in the world but it works. I even like the sound effect of the clock ticking for a second when you start it. It gives a sense of urgency to get started on your task.

Accounting: QuickBooks

QuickBooks on a Mac is lame but my accountant uses QuickBooks so I am stuck with it. The Windows version (which my accountant uses) is totally different from the Mac version but I can export a Windows friendly “Accountant’s Copy” of my “Company File” and I can translate his bookkeeping instructions to the Mac UI. I don’t care enough about accounting software to switch even if there was a cooler Mac-oriented accounting package that could export a QuickBooks Company File to share with an accountant. For personal finances, I use Mint.

Project Planning: Concept Draw Planner

Usually having a white computer gets you out of being responsible for making Gantt charts. However, on the off chance that I need to put together a project Gantt chart, I use Concept Draw Planner. It’s good enough.

Task Management: Things

I didn’t like the changes to iCal’s task feature that came with the Leopard upgrade so I started to use Things. I organize my work into “Areas of Responsibility” like “blogging,” “household,” and “research” and “Projects” a particular client project. Content entry is very quick and the “Next” view gives you a nice hit list of what to do when you have a free moment. Amazing piece of software. Try it!

FTP: Transmit

I like Panic Software’s Transmit.

Bit Torrent: Transmission

I am not saying that I use Bit Torrent but if I did, I would probably use a client like Transmission. :)

Twitter/Friendfeed: Twhirl

It just keeps on getting better.

Chat/IM: Adium and Skype

You can get me on pretty much all of the IM services as sggottlieb. Funny thing is that I have been using IM a lot less recently now that I use Twitter and Friendfeed.

IRC: Colloquy

When I am on IRC, I use Colloquy

Mailing lists

I subscribe to a bunch of open source mailing lists and the best tool for that is Gmail. I really like the rules feature so I can automatically delete some messages (like a build failing) and tag messages by the open source project that they are from. I usually bulk read a project at a time to get caught up on what is going on.

My absolute favorite app isn’t really an app. It is an app launcher: Quicksilver

Quicksilver is a program that runs in the background. When type Ctrl-Space, a little window pops up. I start typing and Quicksilver filters down its index of files and applications on my computer. For example, when I want to launch Camino, I hit Ctrl-space then “ca” and I see Camino. Then I hit enter and Camino launches. Or I type “web” and a bunch of files that have the word “web” in them pop-up including my slide presentation for WebContent2008. That reminds me. I have have to finish that presentation :) .

Managing Projects with Trac

Tuesday, August 22nd, 2006

[This is a continuation of a sporadic series that started with this post]

In open source projects, bug lists are not just to record of defects, they are often also the main organizing system for the project. Bug lists are where new ideas for functionality are captured, releases are planned, and the vision of the project assembles. Not everyone can contribute code, but they can report bugs and their needs. I don’t think corporate I.T. shops leverage issue trackers enough. They mainly see them as a backward looking reactionary tool rather than a forward looking planning tool.

We have standardized on the open source issue tracking software Trac by Edgewall Software. Here is my system for using it….

Usually my first engagement with a client is a short scoping/roadmap project. During this time, I collect high level requirements and put them into a roadmap, recommend technologies, and do some estimation and planning around the initial release of the application. During this phase, I usually work in a spreadsheet because it is quick for data entry and editing. I try to organize functionality into phased releases that balance time to delivery and functionality. I generally follow the practice of making the releases as small as possible. It is also a good idea to organize releases into themes. This makes it easy to communicate to stakeholders what is coming up next and when.

I start using Trac at the start of the first release project. Here is how I configure it:

  • I create a component for each of the major functional areas of the application. Usually there is a “content” component.
  • I create version numbers for each of the releases. 1.0 is the initial release. Then 1.1 for the release after that and so on.
  • To the default ticket types (defect, enhancement, task), I add “port” to represent something that exists in legacy system that is being replaced; and “question.”
  • In the Roadmap section, I create the following milestones for each release:
    • Infrastructure setup
    • Design (e.g. 1.1 Online Calendar: 1 Design)
    • Code Complete (e.g. 1.1 Online Calendar: 2 Code Complete)
    • QA Complete (e.g. 1.1 Online Calendar: 3 QA Complete)
    • Maintenance (e.g. 1.1 Online Calendar: 4 Maintenance)

Trac comes with some basic reports but you can add new reports through the user interface if you know SQL. I create a report for each release (filtering on the version field). The Roadmap page is a dashboard showing how many tickets have been assigned to each milestone and how many are outstanding. When I think that I have a good idea of how to implement a feature, I add comments to the ticket. I can also associate files such as screenshots when I want to show how the feature might look.

So that is how I use Trac as an issue tracker. But Trac does so much more. Since we use Subversion, we set it up to browse the source code repository. There is also a wiki feature which I use for project documentation. In general, when documentation is on a wiki, I find that people become more concerned with the content than with the formatting. That is a good thing because you want to reduce the effort to make documentation current. Formatting puts up an unnecessary barrier because it sets the expectation that something has to be really polished before it is shown.

The Timeline is a view of all that is happening on the project. You can filter what to include from the following options: milestones, ticket changes, repository checkins, and wiki changes. The Timeline view also publishes to RSS so you can see all the information within your RSS reader. However, I still like to get these notices over email which is another configuration option. There is nothing like knowing immediately when someone checks in some code so that you can review and advise if there is a preferred way. Our developers usually add the ticket number to their checkin comment so you can see why the code was checked in.

And that is all there is to it. Trac is a simple tool but extremely useful. All of my clients that have used it so far have liked it although they hate it when I assign them tickets ;)