Why and how we put our terms of service on github.

As a user, I always felt that the way a company treats their Terms of Service shows how much they care about me, their user. For example I hate it when I'm presented with a five thousand words document, inside a small scrolling frame, and a "we have changed our Terms of Service, please read and agree to the new ones" checkbox.

So, when we updated various parts of the Longaccess Terms for the first time, we wanted to do it right. And by "right" I mean explaining exactly what changed, why it changed, and giving our users a way to easily track exactly how the Terms changed.

In addition to a detailed post, explaining what changed, the rational behind the changes and how they affect our users, we also created a GitHub repository where we uploaded our old Terms and the new ones, to make it easy for anyone to track the exact changes, now or in the future.

A short How-To.

Before uploading our Terms to GitHub, I looked around, but I found close to nothing about how to do it: I mean, not how to use git, but how to format the texts, ideas on how to group changes, how to integrate this kind of publishing with the rest of the workflow.

That's why I decided to write down how we did it, to help others and hopefully get feedback that will help us improve the process in the future.

Document formatting.

We decided to go with 70 characters wide, markdown files.

Keeping lines short makes changes stand out. If you just have one line of text per paragraph, a single punctuation mark will make the line (i.e. the whole paragraph in this case) show up as modified in the diffs.

We could have gone with plain text, but it turns out that GitHub will render much nicer the same file if it's indicated as a markdown file. We use very little markdown markup in the texts, just links. We decided that its makes little sense to track formatting changes, so we avoided adding bold, headings, etc. As a bonus, this makes it easier for our designer to copy the source text and paste it in his editor and add the required HTML tags.

From Word docs to Markdown.

OK, our lawyer is used to working with Microsoft Word, and I didn't expect her to change to a plain text editor and git. So, after we had the new terms, I did the following:

1. Copy the terms from Word, and paste to a plain text editor (I use Sublime Text, but any plain text editor will do).

2. Save the text file.

3. The text file has one line per paragraph. I had to break this to 70 characters wide lines and add an extra blank line at the end of each paragraph. There are many ways to do this. I decided to go with a simple on-line command in my OS X terminal. I know, that's not what most people will feel comfortable with, but it works for me.

cat A.txt | sed s/$/\\$'\n'/ | fold -w 70 -s | sed -e 's/ $//' > A.md

Uploading to GitHub.

While editing and formatting the Terms, its handy to use git diff to get an idea how the changes will appear to the end user.

Once our markdown files were ready, we committed the changes to git and pushed to GitHub.

We decided to create releases for major changes, anything that changes our relationship with our users. Small changes (like typos, or minor reformatting) are committed to GitHub, but are not tagged as a separate release.

A user can easily see exactly what changed between to releases. For example, this link show the changes between our January 13, 2014 and May 2, 2014 Releases. (Note to self: We should have included the link in the related blogpost.)

Feedback

This is a work in progress. If you've tried something similar, I'm really interested in your thoughts. Email, tweet or even better, leave a comment on HackerNews or lobste.rs.