I have been working on a large set of documentation for a prototype that will eventually make it into a product. One issue with the publishing system at my company is that it makes doing prototypes, or really anything not within the rigidly and narrowly scoped model, difficult to set up. It takes a lot of work just to get to the point where you can begin writing.
Since time was of the essence and writing is expensive, I decided to do the prototype outside of the publishing system. I also decided to avoid using the rigid DocBook variant we use. Instead, I figured I do the prototype in Markdown using a combination of Daedalus and Ulysses III. It gives me reasonably full featured Markdown support, flexibility to work wherever I want, easy HTML and PDF exporting, and the stack/sheet metaphor fits nicely with topic based writing. The doc set is a stack and each sheet is a topic. The other nice thing about the plan was that it would be easy to take the content bak into XML since despite the complexity of the variant we use, it is mostly formatting markup.
I wasn't sure how well the experiment was going to work when I started, but a few weeks in I think it is great. I was able to rapidly prototype fifteen topics in about ten days. The prototype pages look fairly close to what our actual system generates. I can quickly make changes to the content as needed and republish. The fact that I can work multi-platform is great. I am not chained to my desk. I can demo changes easily. I can even make updates on the fly using my iPhone.
The flexibility does come at a price. Daedalus, the mobile editor, has limited Markdown support. It does not support things like internal linking, images, footnotes, or tables. Ulysses does support all of these things, however it defers to the more limited capabilities of its mobile peer when sharing. It can also be hard to make use of all the Markdown features on an iPhone or iPad unless you are using a Bluetooth keyboard. For example, I still haven't found the backwards single quote used for code on the native keyboard.
These limitations are minor compared to the effort and time saved using the combination. I'm pretty sure that I could not have gotten as far as fast using the normal tool chain. In fact, I'm not sure I could have done it this fast using XML and a more flexible tool chain.
The fact that I am working in text that doesn't have to be structured in a rigid format makes the work flow faster. It provides flexibility for quick changes, yet also allows for topic orientation.
For final production and long term maintenance, unstructured Markdown is not a great solution. There the benefits of the rigidity outweigh the cost. The rigidity enforces uniformity that large groups of variously skilled writers need to create and maintain content at scale.
For small, fast projects or prototyping Markdown, with Ulysses and Daedalus, have proven to be an excellent solution.
