I used to be the “Web Coordinator” in a university faculty, and I often had to provide tech support to the office staff. One morning I received an urgent call from one of the program assistants (let’s call her Carol) who had misplaced her notes, which, among other things, told her how to use her computer. I jogged down to her office, and found her with a panicked look on her face.

“What am I going to do, Steve?” she asked. “I’ve lost everything. I need to print out the reports for [something or another] and I don’t remember how to do it”.

Carol was a product of a time before computers, and had adapted to her new overlords with difficulty. She was only a few months away from retirement, but without her notes, it would be a rocky send-off.

“Don’t worry. I’m sure we can figure it out”, I assured her. “Do you remember which program you use to print the reports?”

“No.”, she replied. “I wrote it down in my book. But I can’t find my book”.

You’ll be relieved to know that she eventually found her book, and was able to print her reports. Earlier that morning she had been thumbing through some files in one of those big metal file cabinets, and had forgotten that she placed her book on top of the files. Luckily it was still there the next time she needed a file.

At the time, I recall finding a lot of humour in Carol’s predicament. It was further confirmation that my parents’ generation, of which Carol was a member, were clueless about technology. Imagine needing a book to tell you how to do your job?!

Fast forward twenty years. I now keep an exercise book where I write down notes on …. how to do my job. At the beginning of each day, I write the date at the top of the page, and I write down a short to-do list. I refer back to my previous entries and copy outstanding items into my list for today. In the back of the book I write down things that I will need longer term, like passwords.

If I lost my book, I’d be in a tight spot.

We will all be Carol some day.

My Own Crisis of Complexity

If only I could keep all of my development projects in my book.

I have more development projects on computer than I can easily enumerate. If I had to guess, it would be more than 300, less than 1000. At any given time, I have somewhere between 5 and 10 projects that I’m actively working on, and an another 30 or 40 that I’m regularly maintaining. Projects span many different computer languages, build tools, IDEs, and server types. Each project is associated with its own set of standard and obscure tasks. Despite almost all of these tasks being automated by build scripts and CI, the complexity of maintenance can still be overwhelming. When returning to a project that I haven’t worked on in a while (months/years/decades), it still takes a while to grok the project and figure out how to build it, test it, and deploy it again.

Projects that use Maven or Gradle are generally easier to dust off than, for example ANT, or ad-hoc projects. A working mvn package or gradle build command can help with building up some early momentum, but it is still only the beginning. Sometimes I get the “Build Successful” message, and then think to my self “Oh good, it builds! … um ..Now what?”

“I know I had a development server set up somewhere to run this before. Let’s see if I made a script to start that up.”

“Which server is this deployed to. And what passwords do I need?”

“The certificates are expired… how do I generate those again?”

“Oh.. there are build profiles called ‘production’, ‘release’, ‘live’, ‘beta’, and ‘staging’. Which one is the one.”.

“Ugh…. I hope I left some clues in the README”.

“Damnit! I can’t remember where I saved that project. Was it in ‘Projects’, ‘Xcode Projects’, ‘NetBeans Projects’, ‘tests’, ‘demos’, ‘work’?!!! Maybe I didn’t save it on this computer? Is it on Github? If so, does github have all the latest changes?!”

A Place for Everything and Everything In Its Place

To summarize, my problem is two-fold:

1. I don’t remember where I saved many of my projects.
2. I don’t remember how to use (i.e. build/test/deploy) my projects once found

What I really need is a book-like medium that includes a searchable catalog of all of my projects, along with any instructions required to use the project. Bonus if this catalog can include buttons or menus to perform the project’s automated tasks.

Over the weekend, I decided that it was time to solve this problem once and for all, so I built Shellmarks.

Shellmarks provides a live catalog of all of my shell scripts including documentation and GUI launchers, all in one place.

Tuxpin: A Case Study

This morning I added an entry for Tuxpin so that I can easily start and stop the development server, as well as deploy it to production. The Tuxpin server app is a PHP/MySQL application. It is built using Xataface, which provides command-line scripts to start and stop the development Apache and MySQL servers. For deployment, I use a bash script that uses rsync to upload the app to the production server.

Up until now, when I want to work on Tuxpin, I start by opening Terminal, navigating to the tuxpin directory, and running xataface start – which starts up Apache on localhost port 9090 with the app.

When I want to deploy it I run bash deploy.sh.

Frankly, this isn’t too bad. However, I can imagine a slightly older version of me returning to this project after many months, or even years, and not remembering what to do. For the benefit of this future self, I have just created a Tuxpin management script in Shellmarks. When he wants to work on Tuxpin, all he needs to remember to do is open Shellmarks. He can then do a simple “Find” for “Tuxpin”, or he can find it in the table of contents:

The Tuxpin section, in shellmarks includes some very short documentation, links to the development server and PHPMyAdmin pages (that will open in the default web browser if the development server is running), and a button to manage the development server:

Pressing the “Run” button brings up a server management dialog with buttons to Start and Stop the server, and another button to show the server status:

This makes it dead simple to start working with the project. My future self won’t need to remember anything. He can figure it all out from the GUI.

The Script

The script is pretty simple.

Let me describe what’s going on here. The script has two parts:

1. The first part is a regular bash script that does the starting/stopping/status checking according to the values/presence of certain environment variables.
2. The second part (after the exit 0 line) is the dialog definition that shellmarks uses to build the dialog.

The documentation shown in shellmarks is set in the __description__ property. Its content is parsed as Asciidoc, so it can include links, headings, etc…

The buttons are defined by sections, whose names correspond with environment variables used by the script.

For example, the following definition results in a “Start Server” button being displayed in the dialog:

[startServer]
   type="button"
   label="Start Server"
   help="Start tuxpin server"
   disposeOnSubmit=false

If the user presses this button it will set the $startServer environment variable to “1” when it runs the script, so that the section

if [ ! -z "$startServer" ]; then
...
fi

is run.

To the future and beyond

I’ve ported one project into Shellmarks. There are hundreds more to do. But all in due time.

If you want to start organizing your life, you can install Shellmarks too.

Learn more in the Github Repo

Photo by Wesley Tingey on Unsplash