The Hiltmon

On walkabout in life and technology

WordCounter

WordCounter by Christian Tietze (@ctietze) does one thing, and does it well:

It counts the number of words you type in registered applications and displays the total on the menu bar.

Most writers I know use several different software tools while writing, like nvAlt for notes, Byword for short pieces and Scrivener for the big things. But each of these has a separate word count (if at all). WordCounter brings them all together in one. Perfect!

Available direct at http://wordcounterapp.com.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.

Sonicwall Mobile Connect for OS X Mavericks

If you are running OS X 10.8 or lower, please refer to SonicWall NetExtender for OS X Mavericks, this only works for 10.9 Mavericks and above.

Step 1: Download from the App Store

It’s available here: Sonicwall Mobile Connect.

There is no Step 2.

The best part of this new edition is that this is a real OS X app and it integrates with Apple’s VPN settings.

Which means you only need to run it once, to set up and test the VPN connection. After that, you can access it from the Network System Preference or the VPN menu at any time.

Tip: If the Apple version of the VPN does not work, try again via the Sonicwall Mobile Connect app. When it asks you to accept the expired certificate, click Show Certificate, then choose Trust from the popups. Enter your password and the Apple VPN version will work from then on.

I have also been told that some older SonicWall’s may not be supported, so I cannot guarantee this will work for you.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.

They Will Not Come

“If you build it, they will come”
– Field of Dreams

On Monday night, June 30, 2014, I’ll be taking the Kifu servers down and putting up a static sunset site.

I built it, they did not come. It’s time to go dark.

I know we built it right. We spent years looking at the market for non-profit management systems and found thousands and thousands of potential customers publicly expressing real needs. We met with many, many different kinds of non-profits to talk about that they needed, and with even more to talk about what we could do. We tested the idea, refined it and sought out more to talk with. We did this for three years. Only then did my partners and I decide to go ahead, set up a company and do it.

When I committed the first line of code on July 5, 2011 at 11:14PM, we knew we had a great product idea for a massive, hungry market. This was a winning idea. We even decided to bootstrap the product, give up our time, effort and potential income to make this thing.

At the time I was independent, running my own company (Noverse), designing and developing systems for Hedge Funds and iOS applications for my own clients. I decided to take the chance that Kifu would work out. So I stopped taking on new clients, I completed the iOS work I had, and I started to spend all my time developing the minimum viable product that was to be Kifu version 1.0.

It was fun.

How often does one get to design and build a leading edge product that you just know people will love, because they have already told you they need your solution. It was designer and programmer nirvana. Coding all day, dealing with some amazing creative people who provided art and words, and occasionally meeting even more potential customers and sharing the idea.

On December 9, 2011, I committed v0.7 and we brought on our first customer. They were so excited and could not wait for beta, and were happy to be our alpha testers.

Turns out this too was a very good thing. A few of our ideas did not work as well in the real world and with this customer’s help, we tuned and made the product even better.

On March 6, 2012, out came v0.9, and we went into beta. Several new customers started to migrate on. We put up the public web site, and started telling folks that the final product would be available for everyone soon.

Almost one year from the start, on July 2, 2012, I pushed out version 1.0.

I had spent an entire year of my life putting this product together and talking to folks about it.

It was ready.

I had built it.

They did not come.

For the rest of 2012, I continued to add features, go out and meet people and show them the product. Almost all expressed interest, they all saw it was better than what they had, that it met their needs and was cheaper than their current process.

But they did not come.

This was the hardest time for me personally. I had spent a year without much income building this thing in the belief that it was what all these folks had expressed was what they needed. And then it was no longer in idea, it was a real product. They all loved it when they saw the demos, and it passed all their tests with flying colors.

But when the time came for them to sign up, they did not. Their reasoning never had anything to do with their need (we filled it) or price (we were better) or quality of product (we hit their sweet spots).

It was “too hard” to migrate (even though we had run several migrations and offered to do it for free) or our company was too small or our track record was too short. Or they did not want to think about it now, or wanted to wait until year end, or “run it up the tree”.

They simply did not come.

This confused me. I did not understand why these good folks were prepared to spend more money on inferior systems that were rife with faults, workarounds and were easy to defraud. I did not understand why they were prepared to spend more to do things manually, incorrectly and frustrate their constituents. I did not understand why they loved my product, spent vast amounts of time and effort discussing and reviewing it, but would not commit to it.

Luckily for me I had Noverse, new clients, new projects and new challenges to get me out of the funk, and put a few dollars in the bank. The rest of the Kifu team were out there marketing, and I provided technical support, new features and demos.

By May 2013, we realized that this was not going anywhere. But we wanted to give it another try, a new marketing push. The product had been out for many months, it was stable and the existing customers were exceptionally happy with it.

They still did not come.

We knew by December 2013 that Kifu was over and started to prepare for the shutdown. It was the right decision to make. There was no point investing more time and effort in a product that had not yet returned any value to us.

We had all lost heart and moved on.

But we did not walk away.

I have spent the last six months making sure that our existing customer’s data is where they need it in the form they need it. And that the servers have stayed up and functional while they migrated away. That has now happened.

It’s time.

On Monday night, June 30, 2014, I will back up the servers one last time, point the DNS to the sunset site and shut it down.

I am happy and proud that I built it. I can still stand up and state truly that I made a great product. I am sad and disappointed they did not come and the product did not succeed. And there is much I have learned from the experience.

sudo shutdown now "Kifu will now go dark"

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.

Hiltmonism - on the Floor

At least once a month, step out of your cubicle or office and spend a day on the floor. It will make you a better software designer and developer, it will help you make better software for the folks on the floor, and it will build a better relationship with them so issues and ideas can flow.

I spent Friday on the floor of my work. As I do at least once a month. My software and their workflows are significantly better for it.

What is the floor? It’s the place where folks will be using your software. If you are writing a warehousing system, it’s the warehouse floor. An accounting system, the desks of the bookkeepers. A trading system, the trading floor. A social network, the coffee shop.

One of the biggest problems with software design and development is knowing exactly what needs to be done. We developers have tried a lot of things, and continue to find new and better ways to figure this out. From requirement specifications, to use case stories, to meetings, to prototyping, all different ways to figure out what needs to be done. We work with analysts and managers to understand the problem domain and make design decisions. We work with some of our users to discuss and test ideas.

But no matter how many meetings and documents and email conversations we have, we developers often miss what the users actually need, want and mean. Communication breaks down like the “broken telephone” game. Our interpretation of the systems and tools may help them somewhat, but just as often, they miss. And our users need to work around the tools we give them to keep going.

But if we, the designers and developers, were on the floor, we could see with our own eyes what our users actually do, and how badly or brilliantly they do it. We can see the problems they face that they cannot communicate, the things they spend more time on than they should. We can see the things they have not mentioned. We can see how our tools really help or hinder them. And we can talk with them directly about it, in context.

There is no way we can get real work done on the floor, we need time and solitude to design and develop. We need to take away from the time spend on the floor new ideas, better solutions or at worst, a clearer understanding of the problem space. And apply our talents to that.

It’s not easy to explain to a manager that you need to take a day off from programming and spend time with your users, sitting next to them as they work or riding along. For some managers, that’s violating the chain of command or “working behind their backs”. For others, they feel they are paying you to program, not to understand, that be their job. The only solution I ever found that worked was to start the conversation early, spend short amounts of time on the floor with users discussing specific topics while they observe and let them see for themselves how much better it works when you and your user put your heads together.

But I think the biggest gain I get from spending time on the floor is the relationships that get built. I get to know my users and how they think, and they get to know me. And once we know each-other, it becomes easier to communicate. I get to learn and speak their language, and they get comfortable enough to start sharing their ideas and issues. And the day you come back on the floor with a feature or change they asked for, that is a very good day for all.

As a designer and developer, I am at my peak when I understand the problem domain, and am pretty useless when not. You can learn only so much from meetings and emails, but without knowing what questions to ask, you will always miss out on the “unknown unknowns”, the things you do not know that you do not know. On the floor you will see things and hear things that you had no idea were happening, can meet the folks doing those things and discuss and understand them. That increases domain knowledge, and that makes you a better designer and developer.

So, once a month at least, spend some time on the floor. Feel the pulse, get involved in the conversations, look out for new behaviors, activities and issues and talk about them, observe and identify the flows and habits, and build a better relationship with your users.

Soon, you will no longer be that mysterious IT person, you’ll be part of the team. Their part is to do what they do, your part is to make great systems for them. Together, every one wins.

I spent Friday on my floor. I learned that my users had no idea certain features they wanted did actually exist, and showed them how to access them. I found out about several design decisions that missed what they needed (and even corrected a few). I found out about a process I had no idea we had. I improved my domain knowledge immeasurably, and look forward to spending more time with them on the floor.

This article is part of a series on Hiltmonisms, a series of catch-phrase ideas that I have been learning, developing and using for years to improve my craft and the craft of those around me.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.

Upgrading Octopress to Jekyll 2.0

So this happened today:

I’ve been waiting for this. Now that it has, I decided to finally upgrade this site.

It was easy. As per Updating Octopress, I just ran:

git pull octopress master

Then, to ensure all gems were up to date, I ran

bundle update

Finally, I got ready - update source, clean caches and generate the blog. Note that I chose not to update the style as I like my SASS changes.

rake update_source
rake clean
rake generate

And it failed.

One thing went wrong and it was because of a old change in Jekyll. You see, before the upgrade I was using the positively ancient Jekyll 0.12. Since 1.11, Jekyll has added excerpts, where it takes the first markdown paragraph in a post and generates that as the excerpt, which it then runs through Liquid. However, I often start a post with the blockquote tag and many of these quotes have multiple paragraphs. The result:

1
2
3
4
5
6
7
8
Hiltmon@Dauntless:HiltmonDotCom (master *) $ rake generate
## Generating Site with Jekyll
identical source/stylesheets/screen.css
Configuration file: /Users/Hiltmon/Projects/Spikes/HiltmonDotCom/_config.yml
            Source: source
       Destination: public
      Generating...
  Liquid Exception: blockquote tag was never closed in _posts/2012-01-26-where-the-light-is-better.markdown/#excerpt

The post had the closing tag, but the excerpt did not.

To correct this problem, I added the following line in my _config.yml to excerpt manually or the whole post:

excerpt_separator: "<!--more-->"

The site now generates just fine.

Once again, my utmost respect and thanks to Brandon Mathis for creating and maintaining this lovely Octopress blog wrapper on top of the excellent work by Tom Preston Werner and the team who create and maintain Jekyll.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.

Server-sided Swift Speculation

Note: This is not a thing, it’s just some idle speculation on my behalf. But maybe, just maybe, Apple will do something like this. Or not. Maybe we will do it.

This week at WWDC, Apple surprised the developer world with their new programming language, Swift. And astoundingly, it’s almost ready for prime time Mac and iOS client software development already.

I would very much like to use a language like Apple’s new Swift on the server side as well. I suspect that we may get some of what we need there, if not all.

Note that I do not see Apple as having a server-side strategy these days. They have iCloud for hosting data and limited apps, and seem to be in no mood to compete with Azure or Amazon in the app server market. They no longer make and sell Xserve servers and Xsan storage, they no longer make and sell WebObjects, their excellent server platform, and OS X Server is just OS X with a few more applications installed. Nope, no server strategy at all. Let the Linux folks have that.

On the other hand, like gcc before it, the clang compiler is open source, available on server platforms and being added to and maintained in public by Apple. Which means that I expect Swift to follow Objective-C in being opened up, available and supported on all clang platforms. Which means Swift could compile and run just fine on Linux distributions which host the world’s servers.

Most server applications these days are built using interpreted languages (such as Ruby (Rails), Python (Django), PHP (WordPress) or Javascript (Node.js)) or runtime-based languages (C# or Java). In most cases, these are plenty fast and stable. But when speed or scalability issues kick in, nothing beats a compiled language. I believe this is why Google is switching to its lovely Go language. It compiles to native, threads beautifully and runs at fully native speeds using far less hardware for the same throughput than anything else.

Imagine if we could use Swift for the same thing. It has the flexibility of a scripting language with the raw speed of a fully compiled native language. It has a REPL and playgrounds for us to play in (not available in Go), a blindingly fast and safe compiler, and all the language features needed to build these types of applications.

Imagine Rails written in Swift for bigger front end web applications that scale and thread without pain. Imagine smaller Swift projects using the Node or Sinatra model for fast and scaleable RESTFUL web-services. Imagine a Swift-based Jekyll to create baked blogs (ok, went too far, this would be completely unnecessary as the whole web server can be compiled in). Using a compiled multi-core language to process web requests would turn things around that much quicker, and yet the language is as easy to use as our current slow-running tools are. The speed of a scripting language with the speed of a compiled language and none of the memory management, buffer overflow and pointer issues. Win-win.

I’m speculating that’s why Google developed and is investing so heavily in Go.

What’s missing, of course, is the eco-system. But that has been written before and can be written again. It would be a heck of a lot easier to write if Apple offered Foundation and a subset of Cocoa. But none of the other scripting and runtime languages we use today had these libraries to start with either and they run just fine now.

I think languages like Swift, Go or maybe Rust are the future of server side. Fast to write, yet compiled and swift running, optimized for safety, reliability and multi-threading, saving us from scaling issues and excessive server costs without increasing the complexity of the application development and support process.

But with Swift, we may be able to go further. One language to rule them all. Shared common code across desktop, mobile and server. All native, all fast, all cores used.

It would be amazing.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.

Omnifocus My Way

I’ve been using OmniFocus as my primary tool for task management for years, yet I never read the GTD book. How I chose OmniFocus is a topic for another day, how I use it my way is the topic for today. Maybe some of the alternative ways I use it can improve the way you do too.

My World

I’m a software designer, developer, project manager and part-time writer. I work at a Hedge Fund by day, run my consulting firm at night, write this blog and have a personal life. As of writing this post, I have 260 active line items in OmniFocus. That is a lot of things to stay on top of.

But with a bit of structure, a taste of discipline and a comfortable workflow, OmniFocus helps me stay on top of all of these things.

Area Folders

I divide up my life by my world. Which means the first level of all my OmniFocus tasks is the in the Projects tab. I have top-level folders for each of the four areas of my life I manage in OmniFocus: Personal, Maritime (work), Noverse (consulting) and Hiltmon (here).

This breakdown allows me to separate and focus on the tasks in the area of my life I am in now. As of writing this, I am focussed on the Hiltmon area. As soon as I post this, I will move focus to my Personal area. I use the OmniFocus Focus button a lot.

Projects

Given that I have a Project Management background, to me almost everything I do is part of a larger project. Whether it’s the multitude of applications to design at work, my consulting clients to support, or bigger ticket items in personal space, they are all projects.

I create all of the projects that I am involved in within each area folder. In my mind, all tasks are assigned to a project. Larger tasks are broken down into sub-tasks, but I do not go into too much detail with these. That happens when I am doing the task.

I also create a few ‘special’ tasks in each project:

  • The Project Ideas task is used to capture (as sub-tasks) thoughts and ideas on what could be done but is not planned, yet. I do not want to lose any ideas no matter the source while I am working on the project.

  • The Project On-Hold task is for sub-tasks that have been placed on hold, but we may still get back to.

  • The Project Later task for sub-tasks that I have intentionally deferred until later versions of that project.

These special tasks often fill and empty during project reviews and meetings as we reschedule what we want to do on each project. I also sometimes have a general Ideas, On-Hold and Later project in each area for nonexistent project related tasks.

Finally, each area folder also has a Single Actions List for those random once off tasks and a Routines Project for the routine tasks that happen over and over again. Tasks from monthly reports to backup reminders to billing cycles appear in the Routines Project for each area.

Contexts

The way I understand it, contexts are where a task needs to be performed or with whom. Since almost all that I do can be done on my laptop, most of my tasks can be done anywhere. Traditional GTD contexts make no sense to me.

Instead, I use contexts as tags, for prioritization and for assignments.

My top five contexts (after No Context) are my prioritizers. I had tried priority levels and colors before, but it added complexity. What’s the difference between a priority 3 and a priority 4 task when the levels are arbitrary?

I use a UI / NUI / UNI / NUNI / Chase / None model for prioritization as follows:

  • UI: Urgent / Important tasks are the ones I need to get done first for each project, in any order.
  • NUI: Not Urgent / Important tasks come next, often because they are dependencies on other tasks.
  • UNI: Urgent / Not Important tasks follow these. To me, they are the tasks that I should be getting on to next once I have the important stuff completed
  • NUNI: Not Urgent / Not Important tasks seem like the rest, but they are not. I treat these as tasks that have an elevated priority over the No Context tasks
  • Chase tasks are special tasks to remind me to chase people for information or deliverables. They sit outside the regular prioritization scale because I review them independently in my workflow (and have an OmniFocus perspective for these)
  • All other tasks have No Context. They are not prioritized as yet and may remain so for some time.

I have left the default contexts (and a few old ones) in place for now, but plan on removing them soon.

I have a special case for task assignments. I use the People context. For example, if I assign a task to Londo Mollari, I set the context to his name. When I sit with people I have assigned tasks to, I can look at just that context to see and track what they are doing. Note that this does not indicate who I am doing a task with, the traditional context interpretation, that information appears in the description.

People

According to the manual, contexts are also used for indicating who you are doing or discussing a task with. In my case, since having a person’s name in the context implies assignment, I need another way.

That way comes from old habits. I use a person’s initials or a company’s short name in the task description itself, and then use OmniFocus’ search to find and filter tasks by these when needed.

For example, if I need something from Satai Delenn, I will create a task like “Get TPM report from (SD)”. If I assigned the TPM report to her it would have her name as context instead. A search for SD) would find all the tasks I need to do or discuss with her.

The reason I bracket the initials of a person is because I use the same TextExpander snippets for people as I do for key marks (see the end of Assembly Notes). It’s really just a habit now.

Another example use of initials would be to track requests from people. If Satai Delenn had asked for feature X, I would create a task in that project called “Implement Feature X (⨍/SD)” to mark it that the feature request came from her. The same search above would remind me to update her on that feature’s progress.

Dates

I put in due dates for tasks that have deadlines, whether I assign them or not. Most of my tasks do not have these though, as they are either dependent on other tasks or not yet prioritized. As of OmniFocus 2, I have also started adding defer dates for tasks I do not want to even look at until then.

I used to put in due dates on all my tasks, just as a project manager puts in task end dates into a Gantt chart. But since OmniFocus does not have task dependencies, delays in one task do not affect another. Which meant that I often had to bulk-change due dates as things changed. Which also meant that due dates lost their meaning and just became a chore to maintain. Nowadays, I only assign due dates to tasks where an explicit deadline is set and there are no dependencies.

Capture

I rarely use the Inbox. Instead, I capture tasks as I hear about them either into OmniFocus directly if the window is visible, or using the Quick Entry box. Since I know what the project is at the time of capture, I find it easier to tab to the project field and fill that in while I am capturing (or click on the project first).

I did try for a while to capture to inbox as the manual says, but my inbox got so messy that I stopped. I still have to clean up later, but at least I can do it project by project.

Notes

I also use the notes feature extensively and in many different ways, for example:

  • For Asana tasks, I paste in the Asana link so I can get back to it later
  • For emailed tasks, I paste in the email body
  • For chase and follow-up tasks, I use notes to track when I chased or followed up (using a TextExpander snippet to put in the date)
  • For assigned tasks, I use notes to track discussion on that task with the assignee until it’s completed
  • And for other tasks, I often add ideas, thoughts or an explanation in case the task description was too cryptic

Review

I did not perform a regular review in the OmniFocus 1 days, but since starting the OmniFocus 2 beta with it’s new Review perspective, I have come to enjoy that too.

For me, the review time is a weekly task to go though each project and make sure that nothing has been missed. I use review time to tidy up badly written task descriptions, close those that I completed, re-prioritize tasks, add or change due dates and jot down notes as I think about each project. The new Review perspective makes this process easy.

Daily Flow

Before OmniFocus 2, my daily flow was to start in the project I wanted to work on and get going with the highest priority tasks. This worked well when I only had a few projects on the go, but I have a lot more on now. I need to stay on top of all of them, not just the current one.

Since OmniFocus 2, my daily flow starts in the excellent Forecast view. I can see the overdue tasks that I have missed, tasks due today, upcoming deadlines, and my calendar so I can figure what I can get done. I flag the tasks I think I need to tackle. I then visit all my ‘hot’ projects to see if there are tasks I need to tackle today for them too (since most of my tasks do not have due dates) and flag those.

Finally, before kicking off the day, I click to my Chase perspective to see who I need to call to chase up today.

The rest of the day is spent working, clearing flags, capturing new tasks as they happen and glancing at the Flagged perspective to see what else I need to be doing. This keeps me on track.

I do it my way

I do not use OmniFocus the GTD way (at least I do not think I do given that I have not read the book). I do use OmniFocus the way that works best for me.

OmniFocus and this my way workflow ensures that I never forget a task, a commitment or an action, mine and others. It keeps me focussed on what I need to be doing now. It reminds me what to do next. It helps build an agenda for what to discuss with people, and what was talked about before. It helps me know what was done and why.

Without it, I could not manage the myriad of projects, tasks, actions, commitments and reminders I deal with every day. And to make things even better, OmniFocus 2 evolved towards my way and added ease of use and features where my way needed it the most. I am sure that for many of you of you, the GTD way works well. For others, you have your own ways to use OmniFocus. This was mine.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.

Solve Tab Hell With Fluid and ChoosyOSX

More and more of our data, applications, communications, reading and work happens via a browser tab on the internet. I don’t know about you but I often have several browser windows open on several virtual desktops all with multiple tabs open.

And I can never find a thing.

So I open a new tab. And start again. Tab hell.

Now this is fine for reading or browsing - you just walk the tabs to see what you were looking at. But for work, when you need to go to a specific web application that you just know you have open somewhere, it becomes a bother. You have to go to each browser window, walk the tabs, switch desktops, walk more. It’s too slow and unproductive.

Wouldn’t it be nice if you could use COMMAND-TAB (⌘⇥) or Alfred or Spotlight to get to that work tab quickly?

The solution I have found is to use Site Specific Browsers for each work web application, and software to ensure that all links clicked go to the right Site Specific Browser. In other words, lets say I want to separate Facebook tabs out. I create a Facebook Site Specific Browser and set it such that any links that contain facebook.com should open in that Site Specific Browser. I can then COMMAND-TAB or Alfred or Spotlight to Facebook without having to look through all my browser tabs.

Can you tell which applications are native and which are Site Specific Browsers? Solution: Google Analytics, Facebook, Asana and Bitbucket are Site Specific Browsers.

Here’s how to set it up.

Site Specific Browsers

A Site Specific Browser is an application that presents the web pages of a single site as it it were a native application. It’s really just a wrapper around your regular browser. To the operating system it looks like yet another native application, which means all the native switching you can do just works.

For example, my Facebook Site Specific Browser looks like this:

Not that there seems to be no browser chrome or address bars, just a regular window frame called Facebook.

I use Fluid for these. You can download it here.

To set up a new Site Specific Browser, launch Fluid and paste in the URL for the site into the form. Hit create and it will create a Site Specific Browser by that name in your Applications folder. You can customize the icon to make it look better too.

To access Facebook now, you can launch it like any other application. It appears on your dock, application switcher and spotlight like a native application.

Aside: If you get the paid version of Fluid (which I highly recommend), you can add scripts to badge Site Specific Browsers and can separate the cookies so vendors cannot track you, for example if you want to keep your Gmail activity separate from your searching activity.

Directing Links

The problem remains if someone sends a link to a Facebook page in an email or message, then that link will open in your usual browser, not the Facebook Site Specific Browser. Which means that tab hell is still probable.

But there is a solution for that too.

ChoosyOSX is an application that allows you to choose which browser a link will open in. You can use it to redirect all links to the correct Site Specific Browser. ChoosyOSX can be downloaded it from here.

To enable the redirect, go to Choosy Settings… / Advanced and create a new rule for each Site Specific Browser. In this case, I am redirecting all facebook.com URL’s to the Facebook Site Specific Browser.

From now on, any Facebook link in any app (or on the web) will open in my Facebook Site Specific Browser.

No more tab hell

And that’s all there is to it. My work web applications are all in their own Site Specific Browsers and any links to them open in the right browser. All other web links open my usual web browser. I can launch and switch between my work web applications as easily as launching a regular application (or clicking a link). And still browse the web as usual otherwise.

At the time of writing, Fluid is $5 and ChoosyOSX is just $12, the massive time savings are certainly worth a measly $17.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.

Melding Scrivener and Marked

If you are a regular reader of this blog, you will know that I do all my writing using Markdown format, short-form in Byword, long-form in Scrivener and generate the final document using Marked.

In short: I write all my work documents, including letters, reports and software documentation in Markdown formatted text files and then format them using Marked and a standard stylesheet (See Letterhead - Markdown Style for how that works). See The Markdown Payoff for why.

In this post, I will share how I set up and use Scrivener and Marked melded together for larger, more complex documents at work and why.

Why these tools?

Just in case you are new to the products, the reasons I use Marked include:

  • I can preview any document I write as it happens in the format it will be generated in, while not spending any time actually formatting it.
  • I only had to set up that format CSS once (and save it as a Marked template). From then on, all my documents gained a consistent form, look and feel.
  • I can export the same document into a myriad of formats with ease.

The reasons I love Scrivener include:

  • I can just write, I do not have to worry about format.
  • I can reorganize and restructure longer documents easily.
  • I can store research and notes inside the same document file.
  • It has a corkboard to remind me what goes in each section of a standard business document.
  • I have full control over all aspects of the content and final deliverable.
  • And it too can output the final document in any format.

Why together, then?

Since I already write everything in Markdown, and have the stylesheet already set up in Marked, I prefer to use these products side-by-side to produce consistent quality results. From a small 1 page letter or memo or a 25 page specification, they all come out looking consistent.

How I use the meld?

While Writing

While I am writing the document, I write using Markdown format in Scrivener. I create a folder for each section and a scrivening for each sub-section. I use the corkboard in Scrivener to note what content should go into what sub-section.

This structure enables me to (a) focus on that sub-section alone, and (b) to never lose sight of the structure of the document and be able to navigate around easily. Note that I only write the sub-section title once as the document title, and will display and change it later.

When I feel I have finished writing a section, and have proof-read it a few times in Scrivener, I like to preview it in Marked. Just seeing the same content rendered the way it will turn out helps me see if and where more work is needed.

If this does not look the same to you, never fear, I’ll show you how to get set it up so that it does below.

After Writing

Once I have completed writing the document, I use Scrivener’s compiler to create the final Markdown document file. This I then open in Marked and produce the final PDF, ePub or web page.

You may note that this final processing has added images and outline numbering for me (compare this to the previous image). I’ll show you how to do this too.

So how does the meld work?

In order to make the meld as seamless and as simple as possible, you need to configure a document folder and both products accordingly.

Preparation

Install MultiMarkdown

In order to access Scrivener’s MultiMarkdown compiler, you need to have MultiMarkdown installed. This is really easy to do.

  1. Go to Fletcher Penney’s MultiMarkdown Downloads Page and download the Mac Installer.
  2. After it downloads, go to your Downloads folder and double-click the .zip file to expand it.
  3. Double-click the installer icon, and follow the instructions to complete the install.

Prepare the Document Folder

I do this because it makes it easier to add images to the Scrivener document and see them in Preview and Final without document changes. You’ll see how it works.

I create a folder for the document and two sub-folders, images and markdown. I place all the images the document needs in the images folder.

In this case, the Star Trek Systems Design is the Scrivener document in the Star Trek Systems Design folder. Below it are two images in the images folder, enterprise.png and okudagram.png. There is nothing in the markdown folder, yet.

Scrivener Setup and Tips

I use a monospaced font with no indent while writing in Markdown. This gives the the feel of working in plain text and gets rid of any Markdown issues with indents.

You can download the brilliant Cousine Font from Google here. Just click the down arrow, then .zip file to download, double-click the .zip file in Downloads to expand the file and drag all files (except the .txt) file into FontBook. You may have to restart Scrivener to see this new font.

You also need to disable Use smart quotes (“ ”) in the Corrections tab as (a) Marked takes care of this and (b) you may need to put some raw HTML in (or image attributes) and smart quotes cause this to fail.

And what about markdown image references? Since we can’t use Scrivener $img tags here as we’re writing Markdown, we need working Markdown image references so we can preview in Marked while writing. The “trick” for image references is to point them to the images folder as follows:

![Enterprise](../images/enterprise.png)

Note the ../images before the file name, it is needed.

If you need to add HTML attributes to the image, use a reference link (I leave them in the same scrivening):

![Enterprise][enterprise-image]

[enterprise-image]: ../images/enterprise.png width="75%"

This is why we turned smart quotes off.

If you now open the Scrivener document in Marked, you will see it in the style you prefer, with images.

To complete the document and set heading numbers?

Since all my business documents need automatic heading numbers, I set them up in Scrivener’s compile options.

Choose File / Compile… or press ⌥⌘E. Click the Formatting option and tick off the title for all document levels, we want them included. Also, set the Compile For to MultiMarkdown.

Then, for each row, click Section Layout…. Type in

<$hn>⇥

That’s <$hn>TAB in the Prefix box.

This will tell the Scrivener compiler to put heading numbering in for each title. You must do this for each level. You only have to do this the first time, after this Scrivener remembers these settings in your document.

Hit Compile and Save the result into the Markdown folder. You need to do this in the correct folder so that image links work (and in my case so I do not get confused between the final Markdown file and the in-progress Scrivener file).

You can now open the final document in Marked for some final touches.

Marked Setup and Tips

While editing in Scrivener and previewing the Scrivener file in Marked, you want the following settings enables in Marked Preferences:

  • “Smart” typography turned on to fix smart quotes
  • Include document titles as Markdown headers so you see them
  • Open .scriv files in Scrivener when opened in Marked

This allows you to preview the Scrivener document in Marked as it would appear when exported.

You can also set your preferred stylesheet in the Style tab to save time when previewing the document.

Any settings for the final exported Markdown document?

I like to have the document name and page numbers at the bottom of the page when I print. In Printing, I set the Bottom-Left to %title and the Bottom-Right to Page %page of %total and changed the font to match the style. I also check the Border / Below Header and Border / Above Footer as I prefer a line there. Click Save & Apply to save your changes.

To print the final document, click the Export Drawer in Marked or press ⌘⇧E and click the Paginated PDF to generate the final PDF file.

And there you have it, a formatted, paginated version of your complex Scrivener document.

Using the meld

It sure looks like a lot of work to get this set up and working, but when you do a lot of these, the setup become easy. Create your first document like this, and for the next, you only need to change the font and compile settings in Scrivener once. After that, it should all just work.

I create a lot of larger, complex business documents this way in Scrivener. It allows me to focus on the content and structure and yet generate a consistent document format each time using Marked.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute#xpost` on one.

The Markdown Payoff

A long, long time ago in a galaxy far, far away, I switched to Markdown format for documents, notes and other scratchings. (And wrote about it - see the posts in the Markdown category).

Was switching to Markdown a good call? Did it pay off? And if so, how?

I actually wrote this post not knowing how it would turn out. I wanted to know for myself if it paid off, or if I just followed a fad. A fun exercise.

BM (Before Markdown)

Before Markdown, I wrote less. I rarely blogged, took occasional notes using pen and paper and often forgot things. If it was not sent via email, I did not have it. Sounds familiar, no?

For plans, manuals and other work documentation, I used Microsoft Word, just like everyone else (See Why Microsoft Word Must Die). I was one of those people who used document styles, but still found myself spending heaps of time formatting my work and then reformatting after other people’s edits.

For everything else, I scribbled notes in a cheap, paper notebook that I never read, on post-it notes that stacked up or on the back of printouts (remember when we printed stuff?) that got thrown out.

Other than after-the-fact documentation, I had no useful records of meetings, designs, thoughts, decisions or what I did. And remembered little of what was said, why things were done or what was done.

It was because I did not have these things that I looked for a simple solution, one that would work for me, and I found Markdown formatted files. I created my own Markdown Mindset

AM (After Markdown)

Since I started writing Markdown formatted files, I have created lots of them: meeting notes, assembly notes, support notes, design decisions, journalling, project documentation, business documents, ideas, proposals, statements of work, contracts, README files, server configurations, copies of quotes and even to-do lists. Everything that I may have written or jotted down is now in a Markdown file. And everything that I was to lazy to record, I now do, in a Markdown file.

I write more. In fact, I write a lot more. I take my laptop (and now iPad) into meetings and take notes that I save. I have BBEdit open at all times with the current project’s notes open, and habitually switch to it to jot down thinking, ideas or even the commands I use. If I get interrupted, I jot a note in a blank Markdown document.

Because I have these files available at my fingertips, I can always get back to what was discussed, what I was thinking or what I did. All the valuable (and useless) information previously lost in the write-only notebook, the stacked post-its or the missing printouts is saved and searchable.

I write everything using Markdown. I write my blog using Markdown in Byword. I write my specifications and longer documents in Markdown using Scrivener. I write everything else in Markdown using BBEdit. Add these all up and the cost is still less than a copy of Microsoft Word.

But is all this paying off?

Payoff Wins (Quantitatively)

The payoff is quite measurable. Binary in fact. I have the information I need and I can find it. Versus not having it!

I have created over 1,600 Markdown files over the past two years. That’s a lot of note taking. I often find myself searching for – or going back to – these notes so see what I did, what I was thinking or what, and most importantly, why decisions were made. Having the information helps resolve disputes or explain why things were done.

If having these files is good, being able to find them by content is better. Paper notes are hard to search. Markdown files, being plain text, are perfect for Spotlight search (or whatever indexing your Operating System uses). I can type in a search phrase and all the matching notes are right there.

To aid search, I use Markdown Metadata to tag files and add keywords (and sped up using Keyboard Maestro macros). To aid in selection, I use a file naming convention (see Text Notes - Going Electronic) that identifies the file kind (meeting, note, idea, etc) and its project and date (and sped up using TextExpander snippets).

The quantitative payoff is clear, I have the information I need in a portable and searchable format and I can get to and create these very quickly, efficiently and productively.

Payoff Feeling (Qualitative)

The quantitative payoff, however, comes from the qualitative payoff. These files exist because I have the discipline and tools to create them. And the discipline exists because I want it to.

Since switching to Markdown, I want to write. I want to take notes, I want to record my thoughts and ideas properly, I want to document things. And after two years of doing it, I still want to write. This is no fad. Markdown takes the hassle out of writing, and removes the barriers to get started.

Not only do I want to write more, I want to write better. I’m a programmer by trade, not a writer (as can be divined by the quality of writing in this blog). But because I write more, I want to become a better writer. I want my documentation to be clearer and appear more professional, my blog posts to make more sense and even my emails to be more concise. I feel that as a better writer, I can be come a better communicator and that is best for all.

The key to Markdown writing is that you focus on the content. Structure, format, look and feel are all secondary. It’s pure distraction-free writing. Which means that you have no choice but to write and think about writing and focus on the content. Which encourages you to become a better writer.

The other issue with writing is that it takes time, but the payoff of Markdown is that you land up spending less time doing it. With no distractions and fast tools, more writing gets done. What you do with the time you gain is up to you, but for me, it means I write even more.

And since I want to (and do) write more, I lose less, forget less and understand more.

The qualitative payoff is that you want to write, you therefore write more, leading to having more notes available when you are looking back.

The Payoff

To answer my starting questions, then:

Was switching to Markdown a good call? Yes!

Did it pay off? Yes!

And if so, how?

I write more, I write better, and I have the information I need available at my fingertips. I also spend less time writing, almost no time formatting (thanks to Marked), and am more productive because I always know what is (or was) going on.

Follow the author as @hiltmon on Twitter and @hiltmon on App.Net. Mute #xpost on one.