Writing Specifications

by Martin Westin in


I have been looking for a good workflow for writing structured text. Techincal specifications and other texts that will eventually become a pdf, Word document or similar. This post will be an overview of what I have that works pretty well. I will use Omni Outliner, MultiMarkdown, Pandoc and Rake in glorious harmony to produce the final document.

What I want is...

  • Good control over the structure
  • Flexible options for the writing environment
  • Automatically generated and updated table of contents
  • Separation of content and styling
  • Version control using Git
  • A painless "build process"

Let's see how I ended up working.

Omni Outliner

I have been outlining, and writing, in Omni Outliner for over 5 years and love it as a general purpose list-maker and organizer. In this context, each item is a heading and the notes for that heading is the body text. This works really well but is limiting on larger documents. I installed Fletcher Penney's MultiMarkdown exporter. This spits out an MD file more of less exactly as I want it. Any Markdown syntax I add into Omni Outliner will of-course be treated as markdown. Bold, italic, lists... all can be marked up in Omni Outliner.

Sadly the iOS version of Omni Outliner is more or less useless to me because of the limited file sharing support. I keep everything in Dropbox and without support for that the workflow becomes very problematic. I hope for this in a new version soon. (Yes I have used DropDAV. No good for me.)

Markdown Editors

I am still evaluating the iOS options. My favorite Markdown app for the Mac, though, is ByWord. It just feels like I am typing fast and am being productive when I am in ByWord.

Another essential (as will become evident soon) app is MultiMarkdown Composer by the aforementioned Fletcher. This app has the killer feature of being able to understand MultiMarkdown and to faithfully export that to many formats. It also has a very nice structure view in the sidebar that makes an OO-refugee feel more at home.

You can also do the trick of exporting you Markdown back to OO by exporting OPML from MMC and opening that again in OO... great stuff. Let's say that again: Using OPML as the file format allows me to instantly jump back and forth between MultiMarkdown Composer (for writing long form) and Omni Outliner (for structuring the document). Shuffling sections (chapters) around has never been easier.

The Multi in Markdown

MultiMarkdown is best explained as Markdown with a few things added to it to better support things that I have found I need in technical documents. One main feature is support for internal references allowing me to reference a section elsewhere in a large specification. E.G. "This uses Feature X which is described in [Common UI Features][]" Those brackets generate an internal link to that section and the extra brackets even allow be to be more casual in my naming of the reference and put the actual heading name inside the second pair of brackets.

Getting It Into Word, or not

I have found a good workflow where I can completely avoid using Microsoft Word. It has been a big win for me to be able to instead use a toolchain more familiar to a software developer.

If you really want to end up in Word

MultiMarkdown Composer does not handle internal references when exporting to a Word document. You have to do a round-trip into Libre Office first if you want to keep those. Yes Libre Office. OpenOffice.org couldn't open the file MMC exported. Neither could Pages or Word itself. NeoOffice cost money these days and I had no desire to pay just to try this one thing.

You open this Flat Open Document and immediately save it again as a Word document and it is ready for Word. The version I downloaded crashed every time when saving a modern Word docx document. Saving as the older doc format (for Word 2003) worked. Good Times™

Pandoc Pipeline With Rake

If you are not a Ruby developer you are probably wondering how I ended up writing about gardening. Rake is actually framework in Ruby to run tasks or macros. In this context it allows you to write pretty advanced automation for converting your Marcdown texts into formatted pdf documents with table of contents, nice design and all sorts of good stuff.

Pandoc is a document format converter. It can take Markdown, for example, and turn it into html, pdf and even a word document. Notably with a little help it can give you a pretty solid E-book build process by taking the pdf and processing it into Epub and Mobi formats for iPads and Kindles respectively.

My rake task locates all markdown documents in a certain folder and processes them all using Pandoc finally outputting nice looking pdfs in a separate folder.

Standing On The Sholders of Giants

I have based my Rake and Pandoc pipeline heavily on that used by Thoughtbot for their E-books. Go to their products page and buy any one of their books and you will get acces to the "source code". That is their entire markdown source text and their rake tools to build the books. Awesome.

Latex, The Not So Fun Part

I leaned heavily on the Latex documentation and examples to hack my way towards to document that looks the way I want. Latex is a horrible nasty markup language for electronic book layouts. It is very powerful but oh so strange and hard to read. If you grit your teeth enough you will be able to style your documents to look pretty much the way you want them to. It is just not a lot of fun but once done that template can be applied to any future document you write.

Version Control

Markdown is just text. Rake is just source code. Latex is also code/text. All this is very well suited to version control. Using Git I get all the conflict resulition help you can ask for and a solid system for tracking changes over time.

Quick Note On Pages

Pages does have a structure mode that looks pretty good. I havent played with it extensively but if you don't want the massive conversion mess described above, then Pages may support enough structure manipulation for you to be happy there... if the iOS integration is to your liking that is. Which is my other reason for going with Markdown.

Disclaimer

Some readers may shake their head and say: I can do all that, and more, in Microsoft Word. Well, good for you. I couldn't figure out that program if my life depended on it. If you know it well and can operate on the structure of your document, move things around, automatically re-assign formatting based on the relative position of something in the overall hierarchy... I'm happy for you and would actually love to know how you work. Personally, I cannot even get Word to properly paste text without going to through the menu using 4-5 clicks.


Winning Two GSMA Global Mobile Awards

by Martin Westin in


Yesterday, Feb 28 2012, Great Connection Inc, the company I co-founded and work for, won two GSMA Global Mobile Awards. We won both categories relating to healthcare and both our nominations. As this is the equivalent to an Oscar or a Grammy in our industry, but far less glamourous, it's pretty awesome.

We won for Best Mobile Health Innovation and mWomen Best Mobile Product or Service for Women in Emerging Markets. As the product designer, lead developer and inventor I am most touched by the the fact that the Judges comments seem to recognize the work of my co-developer and myself.

Good initiative concerning maternal health. Nice convergence of a number of technologies in a critical area of need.

It is not easy to grasp a technical system and product like ours. Mobile Baby spans two very different industries: healthcare and mobile, and also cross many "glass walls". Professional and consumer, men and women, rural and urban and many others. We have built a product that is irreverent towards pre-conceived notions in both healthcare IT and mobile communications and struggle to be understood and accepted in either industry.

The TL;DR or what Mobile Baby is that we connect medical imaging equipment, mainly ultrasound, to the internet and run a hosted "cloud" system tailored to making geography and time a non-issue in the healthcare workflow. Images are available in clinical grade formats online in our web-based application and can be downloaded and opened in Imaging workstation software on iPhones, iPads or "real" computers.

The feature that most people can relate to is the systems ability to provide expecting parents with high-rez images and videos in consumer-friendly digital formats for viewing at home and forwarding to family and friends. The same messaging features that give parents images on their phones is also used to alert doctors of new cases and examinations.

Anyway. I am proud, both for myself but most for my colleges and partners at Qualcomm and Etisalat. Without all these people (too many to mention) and their ability to connect with people and generate interest, hype and trust, I would still be designing this product in even more obscurity than today. :)


Patents Gone Crazy

by Martin Westin in


I am in the middle of some patent applications in the US at the same time as all the recent press about patent "trolls" going after small (and large) iOS developers. These things have made me think more than usual about the patent system. I think the root problems are the following:

  1. Legal costs or defending your patent or yourself from someone else's patent affect the whole patent system. And not for the better.
  2. Patents were meant to protect an inventor from copycats... under the aparent assumption that nonone could independently come up with something near-identical to another invention. That is: you should really only be able to patent things where the likelihood of an independent near-identical invention are slim-to-none. There is nothing in the system that requires you to prove something is a copy... it is just assumed and this works really poorly today, especially in software, where people come up with the same thing independently all the time.
  3. The key term defining what is patentable, "non-obvious to someone skilled in the arts", has eroded significantly. I believe that both the level of "skill" and how much research is required for something to be "non-obvious" have been lowered. Sometimes to ridiculous levels.

I believe the only long-term solution is to invalidate a whole lot of patents and to create a body doing these invalidations without the economic problems associated with lawsuits and courts. This is going to mess things up for a lot of companies and I am skeptical that we'll ever see a significant change.

The applications I have written should probably not be granted patents, ethically speaking. On the other hand they are no worse than many many patents already granted and the lawyers see it as a sure thing that we'll be granted these patents.

It is a very wired position to be in.


Am I Fierce?

by Martin Westin in


I love Dropbox and use it every day. I love Flipboard and use it every day. So imagine my reaction to seeing my (and my co-founders') little company named as one of the 15 coolest young companies in the world next to all these great companies. That was really special.

Fierce Wireless about Great Connection

They didn't get all the details right but if you want to know what I am up to most of the time I have seen worse descriptions. ;)


Minimalist Wordpress Deployment

by Martin Westin in


So, my "sugar daddy" datacenter is kicking me out. This is where I have been hosting absolutely free for a decade so I have nothing bad to say about them... at all. :-) My 4U quad-core2duo, 4GB RAM, 8TB SATA beast will soon become homeless.... Did I mention they let me host that monster for free?

This website was a minor task for that server but last Sunday I moved it onto a minuscule "cloud" VPS at Gelsys. Running PHP and MySQL on 256MB of RAM (and no swap) and expecting a stable server under load did require some tinkering. I am not going to detail every little thing. I'll only outline the basic setup.

I have Wordpress spitting out static html files which is what is being served for 99% of all requests. PHP is only being called on to re-generate the files when the caches expire and to serve up the admin interface. In this way my mini-VPS can handle a pretty decent amount of traffic. I don't generally get a lot of traffic but I am curious to see how the server behaves during a spike.

Wordpress caching is handled by the excellent W3 Total Cache plugin which recently got official support for Nginx. Yay! no more custom rewrite rules. My only problem getting it running this time was that it refused to cache the index page, which is kind-of bad when it is one of the heaviest pages to render. Turned out it was a simple precedence issue. "/" is considered a folder which I caught in a rule before the caching rules had a chance to do their thing.

Nginx is the web server. I have been running it for a few years already but for this it is absolutely essential to save on ram and get the best performance serving static files.

PHP is called from Nginx over an unix socket and served by php-fpm. PHP is compiled with my favorite accelerator eaccelerator. It is just the simplest to get going and has shown good performance for my apps. PHP has been scaled down a lot in php.ini, reducing mainly memory usage and timeouts.

MySQL loves memory so I had to do the equivalent here. Basically taking the standard performance tips and doing the opposite. I know I will only server Wordpress and I know I don't have any enormous datasets so MySQl should be fine on very low memory. Also since I limit the number of php processes I consequently limit the maximum number of client connections MySQL will need to keep track of.

The only other service running is ssh and I was surprised to find that sftp was one of the biggest memory hogs. Uploading a bunch of files of sftp and the server would immediately come dangerously close to running our of memory. In fact it did a bunch of times during my tweaking.

I have been thinking about switching from Wordpress to some static website generator but that is for another time. This setup looks fairly smooth at the moment.


Offensively lazy web developers

by Martin Westin in ,


There exist many websites and web applications with elements of poor usability, engineering, design and so on. Some exhibit features so poor I can only attribute them to laziness. Some actually make me feel offended that I have to jump through hoops to accommodate their laziness. Top of my list are form fields for postcodes, phone numbers, dates, times or any similar type of data. Simple numeric data. Easily validated and normalized. Yet I often see requirements to enter the data in a very specific format, often at odds with how humans customarily write such data. To most people (who are not developers) it can be very confusing to enter data in a perfectly normal way and have a computer tell them it is invalid. For me it is offensive since I know it is practically always the result of data not being normalized. A developer that does not normalize input data before validating it can only be described as lazy or, if you prefer, incompetent.

Postcodes

Nothing can be simpler, right. In many countries it is simply a few digits. Some through a few alphabetic characters in there. I'll focus on local Swedish websites and Swedish postcodes. We have 5 digit postcodes. They are typically written "123 45". So Why would any Swedish website validate that input and claim it is invalid. As a developer I know it is probably that a space is not a numeric character and that adding it also make the string 6 characters long and not 5.

Phone numbers

A phone number is a string of numeric characters. Anything else: spaces, parenthesis, dashes and other chrome, is just that: chrome. None of that is part of the data. No server at ATT, Telia, Vodafone or any other network carrier reads these thing and need them in order to route a call. Quite the opposite. Any phone network and particularly cellular networks require a very specific internationally standardized format. Guess what? It is all numeric. A Swedish cellphone might be typed "0701 - 23 45 67" in my address book but the phone sends 46701234567 to the network anytime I make a call.

Dates and Times

These are a bit more complex than the above. But the same principles apply. Then again, most web-focused programming languages have functions to parse a myriad of ways one could type a date or time and create a proper date or time object or data type. If you still find it does not work for you then, in this case, you should provide something other than a blank test field. Try googling for datepicker or timepicker. The problem will be one of choosing your favorite rather than finding anything at all.

Being constructive

I have ranted a bit now so I thought I'd put my code where my mouth is. Since I am not allowed to share my phone number normalizer code I wrote at work I thought I'd at least share the secret to all the normalizing tasks above... It's regex. Regular Expressions.

Getting rid of whitespace

The following will "match" whitespace characters. By substituting the matches with nothing you will simply remove all whitespace from a string. /\s/

Remove anything that is not a number

And the following will remove non digits if you substitute the matches with nothing. /\D/

A very very very simple example in Ruby


num = "(0)701 - 23 45 67".gsub(/\D/,'')

Seriously. That is all it takes to turn an offensive web form into a more humane one.


My Reasons for Jailbreaking

by Martin Westin in


I don't generally use my iPhone jailbroken. But every time I go on vacation of a weekend trip I make sure I jailbreak the phone in advance. I do this to get access to only a very small number of features that really should be part of the OS.

Internet Sharing using MyWi

MyWi does something so simple and obvious. It allows my iPhone to setup a wifi hotspot and share the 3G connection with other devices, i.e. the iPad. That Apple does not provide this feature can only be described as greedy american corporate bullcrap politics. Wether it is to spare ATT from the network congestion, let them sell more data subscriptions or to just try to sell more iPad 3Gs I can't be sure. My opinion of it stands either way since there is no justification for it based on anything like "the users best interest".

Why not just get an iPad 3G? I am not about to get a more expensive AND less pretty iPad 3G just so I can use the 3G connection a few weeks a year. At home or at work I have wifi but, at least in Sweden, we don't generally find wifi hotspots in our rural countryside. Unlike the US, we do have 3G connectivity almost everywhere and Edge everywhere else. And, also unlike the US, we have no carrier restrictions on which device is allowed to take advantage of our mobile data connection.

The Apple-approved alternative is to carry along my Macbook pro simply to act as a Wifi hotspot for the iPad by... sharing the iPhone's 3G connection. Same result but more weight, power, bulk and complexity. Since using the iPhone as a modem for my Macbook pro is available, why not for the iPad? If not via wifi, how about a dock-to-dock cable or something? Maybe they just like me to lugg around all my Apple products :)

Keeping up-to-date with my podcasts

Podcasts are generally released on a weekly or daily schedule. But, since they are also generally over 20MB I am not allowed to download them to my iPhone without a wifi connection. Again, not a problem when I am at home, but a big problem when I am travelling. Again (again), a nonsensical and arbitrary restriction. I can understand a warning. But with so many "unlimited" dataplans for the iPhone and so many other types of data (YouTube anyone?) that exceed this limit I can't understand the restriction. Fortunately, in Cydia I can buy and install "3G Unrestrictor" which does exactly what you'd expect. It removes the restrictions related to the mobile connection.

That is all. The iPhone is that close to being more or less prefect. Two "missing" features that I believe are the cause of the network situation closer to Cupertino (more Wifi than 3G coverage one is almost lead to believe) and splash of arrogance and excessive greed. Neither feature is a deal breaker most of the time but both make my life a small hell when I am away for a week or two.

There is of-course annoying things like complicated file transfer setups and other design decisions that cause problems once you start wanting to actually transfer information in or out of your phone. But those are not so easily solved :)

Also I should note

Well over 90% of the things found in Cydia are crap (my opinion). There are however a very small number of Cydia packages that I actually find useful to have on my phone. A few more are cool in a geeky way but nothing I need on my phone on a daily basis.


Developing my first iPhone App

by Martin Westin in


While my friends were playing Red Dead Redemption I finally got my feet wet in the iPhone SDK. My first app is available on the App Store after a surprisingly short development time. The app is called Extraction and it is a simple Espresso timer for coffee nerds like myself. You can read more about it at extraction.eimermusic.com. Describing the app is not what this post is about.

What I wanted to write about was the design, development and the resources that got me going. I have never before coded in Objective-C or any C-based language for that matter. The closest environment I have developed in is Flash. Kind of ironic considering the current Apple - Adobe relationship.

I got from 0 to a submitted app in about 2 weeks... And to that I should add that I could only read, watch and code briefly every now and then. I was taking care of my 1 year old son full time during these weeks. I estimate I coded, designed and tinkered for around 15 - 20 hours total.

So what helped me get started and actually complete a real application with navigation controller, camera support and data persistence?

The Idea

Being an espresso nerd I had a look around for a timer application that would let me time my shots and mark that "lap time" for when the coffee first starts flowing. The ones I looked at didn't do it for me. A bas example is the built-in stopwatch on the iPhone. Marking a lap time makes the "main" timer start over from 0. Good for running laps but bad for marking the pre-brewing of an espresso extraction.

Developing an app that did this was just my best excuse to try developing for the iPhone. I have been wanting to do that ever since I first got my original iPhone in Feb 2008.

The Design

The initial idea had been brewing for a long time. By contrast, everything about both the design and the development was very quick and intuitive.

The feature set, or "interaction design" if I want to be posh, was arrived at by a bit of iterative trial and error. My initial thought was completely flawed once I started using it. So flawed I wont even go into it. I quickly realised I could store the times. Once that was working I realised I would want to add some notes about the particular shot. And then the obvious thing was to add camera support to allow for a photo of the shot to be saved along with the times and notes.

Once the 1.0 features were sort of working I started to look into the visuals of the app. It started with raw GUI elements in Interface Builder which I sized and placed until they felt ok. Then I basically just imported a screenshot into Illustrator and drew vector graphics for each element and exported them as png files. It is a good thing I prefer Illustrator to Photoshop since making high resolution graphics for the iPhone 4 was simply a matter of exporting from Illustrator @ 200%. Done!

The logo was just a manual vector trace of the first hit on Google images when searching for coffee beans. I am sure you can find the same image by searching now.

I got the colors for the application and the logo from the gallery at Color Schemer. I chose a scheme called Cold Espresso which looked and sounded appropriate.

The Development

Downloading the SDK and opening Xcode frankly got me nowhere. There is a certain amount of implied knowledge needed. I aquired this knowledge mainly from the following sources.

Lynda.com has a very nice video series on the subject that a friend of me downloaded and let me watch. Thanks Mikael. These videos are very short and to the point. Nothing like the sleep inducing Stanford lectures on iTunes. You quickly get a feel for how to code in Xcode and important elements in UIKit are exemplified one by one. Very nice.

iPhone Programming: The Big Nerd Ranch Guide, released only a few months ago was my other main source of knowledge. This one goes a lot deeper than the video series but still keeps the information grounded in the code and not too abstract and philisofical. From this book you really learn a lot of good practices and essential things you need to know to actually make a finished iPhone app for the App Store. Highly recommended.

I did buy another SDK book but I haven't even opened it and can't remember the name. It cost a lot though. I remember that part.

When I got lost on some detail Google almost always directed me to stackoverflow.com. They got the answers to everything there. A few specific problems had their answers at iphonedevsdk.com. They have a great forum there.

After embracing Objective-C and all its square brackets and very long verbose method names... I love it. Objective-C is pretty cool but Cocoa Touch is amazing. Rubyists usually joke that you can do almost anything in Ruby with one line of code... I feel the same about Cocoa Touch. And messaging in Obj-C is really wonderful. you never have to wonder what an argument is doing since they are all labeled as part of the method name. Strange at first but fantastic now.

The Website

Just as I was ready to submit to the App Store I noticed that I needed to have a support website for the app. I uploaded the app and gave myself a very tight deadline to complete a decent looking one-page website for my little app. I'd say the website looks OK at first glance. But look a little closer and you can clearly see it was conceived, designed, copy-written and coded in about 3 hours.

That is all I can think of writing. Anything you want to know more about?


Extraction 1.0 and 1.1

by Martin Westin in


Version 1.0 of Extraction, my first iPhone app, was released on the App Store yesterday. I am very excited about the whole thing. Duh!

Version 1.1 has already been submitted for review. It adds iOS4 compatibility and iPhone 4 high-res graphics.

Extraction is a simple timer and records-keeper for espresso brewing. You may need to be unhealtily interested in making coffee to get the purpose the app. You can read a bit more about the features on the extraction website and you can download the app and check it out on the App Store.


My work at the 2010 CES in Las Vegas

by Martin Westin in


This is so cool

[caption id="attachment_95" align="alignnone" width="440" caption="Paul Jacobs (left) and Eric Topol (right) demo Mobile Baby at CES"]Paul Jacobs (left) and Eric Topol (right) demo Mobile Baby at CES[/caption]

My work at Great Connection: developing, filing patents, taking meetings, and most of all drinking coffee, has finally been outed is a significant way. Dr. Paul E. Jacobs, the CEO of Qualcomm and Dr. Eric J. Topol, a most prominent medical doctor working to improve IT in medicine, demonstrated Mobile Baby at the Consumer Electronics Show in las Vegas on January 8, 2010.

Mobile Baby is the coolest application in the system I develop at work. The service transmits medical images from echo machines (ultrasound), CTs, MRs or any similar digital "x-ray" type device, to any mobile phone, any email inbox and a few social networking apps.

I am humbled and very happy that these "big shot americans" have taken notice of the work have done and say such nice things about it.