Sphinx Laravel Package

+++ date = "2017-04-02T22:01:15+01:00" title = "Prototyping with markdown" tags = ["markdown","prototype", "hugo"] categories = ["design"] description = "An idea to make website protoype with markdown" draft = false weight = 30 +++

{{< rawhtml >}} {{< rawhtml >}}

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 Hugo generator. It gives me reasonably full featured Markdown support, flexibility to work wherever I want, easy HTML ,nd the stack/sheet metaphor fits nicely with topic based writing.

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.

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 Hugo, have proven to be an excellent solution.