If you're a techie like me, chances are you hate Microsoft Office with passion. If your company is still emailing Word files back and forth internally, just stop it. You're wasting your own and other's time (not to mention that you're filling your mailbox with crap). There are far better ways to do this.
Many modern companies are using Google Apps for their email. With that, you get Google Drive/Docs, which isn't all that bad. It certainly is a big step forward compared to emailing files back and forth. However, in this article we'll explore a different approach. The main goal of this approach is to leverage tools from the developer toolkit that solved the collaborative problems a long time ago.
Deciding on a document language
At WireLoad, we're big fans of Markdown. We've used it for years for everything from blog posts, to page content and most recently even for legal documents. The benefits of Markdown are clear: it's easy to read and write for all types of users and it is widely supported across text editors.
There are however some drawbacks. When writing documents with Markdown, you'll likely miss things like page breaks. Some implementations of Markdown do support this, while others do not (it's '*****' in those that do support it).
Since we do need this, what we've done is that we use LaTeX for features that are missing in Markdown (more about that later). A document could then look something like this:
# Hello world
This document was generated on \today.
\newpage
And this will appear on the next page.
As you can see, it's pretty easy to read even for non-technical users.
There are other formats that you could use too, such as ReStructuredText. In theory, you could even use plain text, but as you'll see that would be less desirable later.
Collaboration
As mentioned in the first paragraph, we're going to draw inspiration from the developer toolbox for document collaboration. The two obvious collaborative environment's would then be:
- A git repo (or your SVC of choice)
- A wiki
At WireLoad, we opted for using the Wiki since we already use Phabricator extensively and the built-in wiki offers great features. For instance, you can set a custom permission policy for sensitive documents. Another benefit of using the wiki is that you get live preview.
Markdown/LaTeX/ReStructuredText to PDF
When you're done collaborating on the document, chances are you need to have it signed (if it is a legal document). In that case, Markdown won't really do. You will need to create a PDF.
Luckily, there are plenty of tools out there that can convert markup languages, like Markdown, to PDF. The tool we use is Pandoc. Once installed, you can create a PDF with a single command (or use this Docker container).
If you have Pandoc installed locally, all you need to do is to run:
$ pandoc -V geometry:margin=1in -t latex -o myfile.pdf myfile.md
Using the Docker container, you can just run (this will find and convert all Markdown/LaTeX files in the folder):
$ docker run --rm -v /path/to/docs:/docs vpetersson/pandoc
If you prefer a GUI, there are a number of other tools that can do this too, including Marked for OS X. One of the benefits with using Pandoc however is that it allows you to mix and match LaTeX with your Markdown.
Signing
With a PDF ready for signing, we need to upload it to a digital signature service. Our service of choice is HelloSign, as it's reasonably priced (compared to many others), and has a good user interface.
Storing the signed copy
After the customer/partner signed the copy, you get a signed PDF back from the signing service. In Phabricator, you can simply attach the signed copy to the Wiki page, but you could as well store it in a Git repository.
