A few days ago I wrote a post calling for the Steem white paper to be updated, and suggested that it could be version controlled, just like the code.

"Version control" is a means to manage changing files, and the conflicts that arise from collaborative file editing. File changes (read: versions) are tracked, and is mostly applied to plain text as it's much less efficient for binary or encoded data (like images for example).

Importantly, we can see the changes from one version to another subsequent version by using a diff tool which (you guessed it) shows the differences.

There are several version control systems, the best in my opinion being git, which is used here.

Example: The Constitution of Ireland

Note that English only is used. The actual document is in two languages, English and Irish. It's also interesting to note that the Irish version takes precedence over the English one in a dispute, as the first language of Ireland and therefore the government there is Irish, though as I understand it hardly anyone uses it in real life.

The most recent amendment, 34th amendment on marriage equality

A few years ago the constitution of Ireland came to my attention because of their voting on legalising "same-sex marriage", or what proponents prefer to term "marriage equality". As a fundamental issue of rights, by the Irish system it needs to be recognised in the constitution. Any amendment to their constitution must be voted on by referendum, which is a popular vote of the whole country (Republic of Ireland remember, not including Northern Ireland) and win with a majority of over 50%.

The proposed change was to add a single line:

Marriage may be contracted in accordance with law by two persons without distinction as to their sex.

It ending up passing, much to the joy of progressives, and the 34th amendment was enacted several months later.

At the time I thought, well what is the context of this line? So I looked at the document and the proposed amendment and saw it goes in Article 41 "The Family". The context is important as for the Irish the family have a central role in the view of law, and have special protections. So it's about more than just marriage.

Here's the diff for that:

See the change on GitHub

You can see where it is added and to what. The proposed 34th amendment (which became an act of government, see below) does not give that on its own, and in fact the document in which it is included is only available if and only if the proposal is accepted.

Amendments are like code

If you read the text of the THIRTY-FOURTH AMENDMENT OF THE CONSTITUTION (MARRIAGE EQUALITY) ACT 2015 it reads kind of like code, or instructions of what to do to the constitution. So they're basically like patches.

Really interestingly, if you look at the original document of 1937 (when the Irish Republic was founded) the first "amendment" is actually contained in the document as instructions.

Article 52

1. This Article and subsequent Articles shall be omitted from every official text of this Constitution published after the date on which the first President shall have entered upon his office.
2. Every Article of this Constitution which is hereafter omitted in accordance with the foregoing provisions of this Article from the official text of this Constitution shall notwithstanding such omission continue to have the force of law.

So it is, or was at the start, a self writing document! In other words, it contained instructions which were to be executed on itself, very much like code in the sense that this change is conditional on the first president being elected. Pretty interesting.

See the change on GitHub

Versioning and viewing the diff

The 34th amendment was a very small change (not without big impact), but not all other amendments (and amendment-like changes, as mentioned above) we small. Wouldn't it be great to see the changes, side by side?

Here's a few changes that caught my eye and that show the power of versioning and the diff tool.

Note, dates are enactment date

Also note, you can also see diffs in GitHub at the provided links, but I prefer JetBeans' IntelliJ IDEA which I use for coding.

5 January 1973 - Fifth Amendment. Removed reference to "special position" of the Roman Catholic Church and to other named denominations.

See on GitHub

---

7 October 1983 - Eighth Amendment. Intended to entrench the statutory prohibition of abortion at a Constitutional level.

The 13th and 14th amendments also dealt with abortion, to do with prohibiting the restriction in travel to seek abortion and distribution abortion information.

See on GitHub

---

17 June 1996 - Fifteenth Amendment. Removed the constitutional prohibition of divorce, but retained certain restrictions on its occurrence.

In the same article "The Family" as our first example.

See on GitHub

---

2 December 1999 - Good Friday agreement enactment

This is an interesting one (not least because of it's actual content), where you can really see the wording changes. Note that the "accordion" areas collapse parts of the text so we can see just the changes.

See on GitHub

Process

I decided I would version this document and step through each change using the popular versioning software called git. You can see the resulting repository (i.e. project) here, on GitHub.

I Started with the original text from 1937, and converted to Markdown format. I followed each of the amendments and applied them as per the instructions.

The actual enactment text, which are always acts of government, I got from the official Irish Statute Book website. The text I used for the commit messages (the message you add when making a change) I copied from the Wikipedia article on the amendments. Note that not every proposed amendment passes, and these unaccepted amendments were skipped. It would be interesting to branch off for each of these and show the changes anyway.

The amendment instructions are extremely clear, as you would expect, as ambiguity is often debated (that was a hot topic for the most recent amendment) and so it wasn't that hard, just painstaking!

The result is the GitHub repository as mentioned, constitution-of-ireland-markdown.

Using this methodology for Steemit

On Steem (and other similar projects) I think you can think of the white paper as the constitution, and the code as the legal framework and actual laws. The laws need to be consistent with the constitution or they are invalidated.

This is important because not everyone is a lawyer and so is not in a position to interpret legal text. But any literate person of moderate social knowledge should be able to read and understand the constitution. This is similar to developers, who can read, write and design code - not everyone can nor should be expected to be able to do this, but everyone of moderate technical knowledge should be expected to be able to understand the foundational document.

What we could do

I think amendments could even be proposed using the familiar version control method of:

1. Make a copy of the document (fork)
2. Make proposed changes to document on your own version (edit and commit)
3. Propose these to the document owners (pull request)

The resulting pull request can be debated in comments on GitHub or similar software, and finally accepted or rejected by the document owners.

For some things it would not be necessary, just as it's not necessary to amend the constitution to enact some laws. But for anything significantly important or fundamental, it should be.

Anything to do with mining, witnessing, author and curation rewards, payout in general, etc. I would consider fundamental. A prime example of this is removing Proof of Work (PoW) i.e. disabling traditional mining, in hard fork 17, currently pending acceptance by Steem witnesses. This is huge really, even though it's effects now will be small. It is through this mechanism that Steem got started, so updating the document to reflect this is important.

Technical things which are pretty much implementation only (like NTP is disabled by default proposal in HF 17) can be left out and exist in the code.

A benefit of versioning regarding document sprawl

If we use versioning, there's no need to explain changes in the current document because their history is plainly there. For example, if removing the PoW part of the document, there's no need to say why, the commit message would explain it in brief summary, with more details available elsewhere.

This means the document can be at all times current and unbloated.

What we should probably actually do

It would be good to maintain a document that is based on the whitepaper which could include all important information about Steem.

Then going forward we can all contribute to maintaining it on GitHub, just like the source of the blockchain is maintained there too. This means no one person would be completely responsible for it.

Obviously the authority to accept or reject pull requests should be in the hands of the official devs, as it is they who know best how the code works.

It strikes me that ideas of change can even be proposed and debated in this way long before code is proposed. In a well managed system this will always be the case, and I'm sure it is the case with Steem, but this would make it easier for the "lay" person to understand and I hope would improve future hard forks.

Answer the call?

@biophil if you are still interested? And are you stuck on LaTeX? If you can make a good argument for it I'll go with it, otherwise Markdown seems to be to be the best option. The only reason I can think for using LaTeX over Markdown is better rendering to print quality documents, but I'm not sure this is relevant. Also Markdown reduces the barrier for newbies to contribute, one less thing to learn.

EDIT: LaTeX is my new favorite thing! From working on it a little it's actually perfect for the job

Anyone else interested? @ned and @sneak, care to comment?

Disclaimer

Please don't read any of this as support for statism or democracies. It's just an example, one which I enjoyed a lot. Understanding structures of power is advised no matter what your political persuasion though and reading it was illuminating, especially on the changing attitudes of the Irish in the last century.

Finally

Thanks for reading! 😁 This was a fun project and I hope it leads to something on Steem.

Attribution

The "cover photo" for this post was made by combining two images:

1. Leinster House - 1911.jpg uploaded by Zanaq to Wikimedia Commons, but a public domain image
2. Antu state-fork.svg by Fabián Alexis, originally at this GitHub repo which is licensed under Creative Commons Attribution-Share Alike 3.0 Unported, and allows sharing and modifying when properly attributed