Blog

Contracts

Writing contracts is a pain. We all know that. Is there an opportunity in this pain to find an easier path? Let’s explore together what it would be like to automate part of our new work intake.

I want to take you back to a time when you were a newer developer, and you found more joy in discovery than pain in processes. Like me, if you slowly moved from doing more development work to having to wear the hat of an owner or lead, you started having to write a lot more documentation.

What would you say if I told you there was a way to bring that creativity back to writing contracts, and allow yourself the ability to be creative and flexible, without having to fight with Microsoft Word and it’s formatting.

Let’s explore what that would be like, together.

So you probably have already heard of Markdown. It’s a lightweight markup language that John Gruber created in 2004 while collaborating with Aaron Swartz on the syntax. The key design goal of Markdown was readability.

For example, the following markdown code:

Horizontal rule:

---

Bullet list:

  * apples
  * oranges
  * pears

Would produce the following HTML:

<p>Horizontal rule:</p>

<hr />

<p>Bullet list:</p>

<ul>
<li>apples</li>
<li>oranges</li>
<li>pears</li>
</ul>

With a few other simple tags you can see how easy it is to approach the utility of a full text editor, all while writing common keystrokes and not having to interact with a menu. This keeps creativity flowing.

These simple symbols allow many options.

A few *simple* symbols __allow__ many options.

A few simple symbols allow many options.

Now, that itself becomes a pretty useful way to generate code, and in fact a large number of websites secretly use Markdown in the background in order to give users simple options to custom format text.

The magic of open source is that you can combine different elements to do new things.

There is a document conversion utility called Pandoc. Installing it on your system allows you the ability to convert documents that are simple, like markdown, to formats like PDF, Microsoft Word and many, many more.

What’s more, Pandoc supports the ability to pipe the markdown text through a template file to achieve a completely custom look.

Imagine the flexibility this provides.

The current workflow for many document centric businesses is to create documents, cutting and pasting from other templates, examples, previous work.

This is the problem, with this workflow. Cutting and pasting formatted text is a nuisance at best and a nightmare when at its worst.

Many blogging systems have either had “paste from word” functions explicitly set as options or do Word formatting cleanup behind the scenes.

The magic of composing all your documents in Markdown is that you never need to worry about all these styles blending when you edit text.

With Pandoc you can specify a template file, which applies all the styling to your document as the text is poured into it.