I wish government legislature did this with their bills. Reading a piece of legislation is maddening because it's always just a description of diffs, without seeing the final outcome.
I never really realized that this symptom was common with RFCs as well.
Is there something about how governing bodies work that lead to this style of output? Why aren't we using a bit more modern techniques now, more akin to how word processors let you see the diffs inline but also the final format? Or git-style PRs that show the deltas but you can always just view "main"?
This is the natural end result of committee-style work - because if you work on a "diff" you can force the discussion to only touch some small parts of the whole, but if you work on an "updated document", even if everyone kind of agrees the only change necessary is to Section 7, the fact that the whole document is "up for discussion" causes the whole thing to be up for discussion.
In both cases they can still produce the "final document" which the government is often better at than standards bodies.
A possible counter model to this kind of organization is how the Nicolas Bourbaki collective organized their work:
"Subcommittees are assigned to write drafts on specific material, and the drafts are later presented, vigorously debated, and re-drafted at the conferences. Unanimous agreement is required before any material is deemed acceptable for publication. A given piece of material may require six or more drafts over a period of several years, and some drafts are never developed into completed work. Bourbaki's writing process has therefore been described as "Sisyphean". Although the method is slow, it yields a final product which satisfies the group's standards for mathematical rigour, one of Bourbaki's main priorities in the treatise."
This can work when you have a defined mathematical result you're trying to get to - in most standard bodies this would result in never releasing a standard, ever.
But what if the changes were proposed as an actual diff to the original document, similar to a pull request, so that once it is approved, it can be combined into a new version that fully replaces the old?
They often are, but the standards groups don't seem to actually produce that changed new version (likely because they wouldn't have a way to reference it?) - governments just implement the diffs in the law.
That's one of the functions of the Federal Register. It applies the diffs so to speak to produce the actual code (by code here I mean law code). But yes in theory you can challenge that in court by showing they applied the changes incorrectly or something.
And FWIW every once in a great while the government does tend to reset the baseline, declaring a specific version of the merged code as the single truth. So even if there are errors or whatever from previous applications of various bills it doesn't matter and courts can't examine that. This prevents every bit of law from potentially being subject to reconstruction from the first congress forward. I believe the current base revision is from 1986.
They often do have version and revision numbers. As well as final release numbers. I find the biggest issue is the lack of ability to trace the document forwards in the repositories.
Usually an update will list which documents it updates but often it's much harder to find if there have been any new updates that have further obsoleted this update.
Not just that, there's also the fact that the result of the committee work will then be put up for vote. That's basically an enormous code review, if not enough representatives press "accept" nothing happens.
Imagine having to review code changes without a diff, e.g. with only the before and after states, on separate computers. Bad idea.
> (1) EXPANSION.—Subsection (e) of section 1710, as amended by section 102(c), is further amended—
> (A) in paragraph (1), by adding at the end the following new subparagraphs:
Your example is a bill that hasn't become law yet; so it has not been integrated into the US code (the "final document"). When the president signs it and it becomes law, the change specified there will be made. You can find the US code, as it is in effect today, among other places, on the site of the House: http://uscode.house.gov/
What I'd love to see is a place where I could view a bill and also the code it impacts, with inline diffs for the relevant bits (but not the dumb formatting / bullet numbering stuff).
In the IETF's case, this is because, by policy, RFCs are immutable once published. You can update an RFC by publishing a new RFC that specifies the changes, or a new one that obsoletes the original entirely (this document does both to various RFCs). There is also an errata process for simple mistakes.
That means that minor changes tend to accumulate in other documents over the years. You could imagine tooling that automatically incorporates these changes into the presented document, like you suggest, but someone would have to build that tooling. That is a bit challenging, as the format of an RFC that updates another is not designed for such automated processing (e.g., go read this document and tell me what changes should be made to the text of RFC 5961, which it updates), and because the format of a published RFC is not semantic (e.g., adding a new section will not automatically renumber the remaining sections, because it's just a .txt file).
You could also design a different policy, but immutability has its advantages, too, and the current policy has been in use for decades, so the case for switching would have to be pretty compelling.
So for now the "Updated by:" header at the top of each document is what you get.
Technically all "update" RFCs could be "obsolete" RFCs - just copy the whole previous RFC and change the parts you wanted to change. The only advantage of "update" RFCs I can think of is that it tells the reader precisely what is being updated, but that can be done by just a changelog.
> I wish government legislature did this with their bills. Reading a piece of legislation is maddening because it's always just a description of diffs, without seeing the final outcome.
Most governments do maintain a consolidated version of their laws, but that's something different than the bills. Compare it with GitHub: the consolidated version is the head of the repository, while the bills are Pull Requests.
E.g. for the US there's the US code: https://uscode.house.gov/; which for every section has both the text as currently in effect, as well as a list of all historical amendments.
> I wish government legislature did this with their bills. Reading a piece of legislation is maddening because it's always just a description of diffs, without seeing the final outcome.
The state of Washington does. Our legal code is called the "Revised Code of Washington" because there is a state employee, called the Code Reviser, whose job description is "apply the diffs":
They do a great job, too. Each section/subsection of the RCW comes with links to the bills which revised it, and each of those is formatted using strikeouts (removed text) and underlines (added text).
The federal government should be embarrassed by this.
The UK does this (but only since 2006, ish, and it's not guaranteed to be fully up to date everywhere). For example, here's an act made in 1981 and amended many times since:
Inserted or altered text is in heavy square brackets, and removed text is replaced with a row of full stops; both are labelled with a code starting with F, which indexes a reference in a box below the section. The references are hyperlinks to the amending legislation; sometimes there is a link to both an act which enabled the amendment, and a statutory instrument which applied it.
There's a slider at the top which lets you see the legislation as it stood in the past (as far as 1991), before each amendment was made.
Amendments made before 1991 are applied, but not sliderable:
Some governments do. For instance, check Brazil's constitution: http://www.planalto.gov.br/ccivil_03/constituicao/constituic... which has for changed articles both the original text (in strike through), the updated text, and hyperlinks to the legislation which was the source of each change. (And it's not just the constitution, all federal legislation has pages presenting in that format.)
This process pre-dates computing. And the law in general defers to precedent, history, and customs - that's part of what Common Law is.
Eventually the legislative process will catch up and use something akin to version control. But that's just automating what is currently a manual process. And the bottleneck for making progress isn't the difficulty of updating the law - not by a long shot.
FWIW some bills just say something like:
1. Strike 27 Section 2(g) (which is 100 paragraphs)
2. Insert the following under 27 Section 2(g) (followed by an entirely rewritten bit of law)
Even all the sections, paragraphs, etc with the numbers, capital letters, lowercase letters, and so on are really just a manual form of hyperlinking and bookmarking so the code can have cross-references.
That's also something that could be a lot easier to write, update, and read if we had a VCS for writing laws.
> Why aren't we using a bit more modern techniques now, ...
because those in power don't care, this problem doesn't really affect them, they don't know about potential solutions (too old and/or not programmers), they are afraid of structural change anyhow, etc, etc.
Your response seems to have a political bent to it, though I could be presuming too much. Assuming you intended for it that way: how does that explain RFCs seemingly behaving the same way? That's about as techie as you can get!
Legal case research is is even worse, if you can imagine. Digging through court decisions is all about finding chains and piecing together the current precedent. Oh and in the old days of legal reference texts, you always had to check for the "pocket parts". Updates to the law after the text was published went sent out as small pamphlets, much like errata, and they were literally placed in pockets at the back of the books.
Most changes are in self contained documents because they are inherently experimental. After a while they become so useful and widespread that everyone needs them, and hopefully a bis rolls them all up.
Yes, it's common. Usually each country has their own cottage industry of providers that mitigate this problem. (By git-ifying the text of legislation.)
I never really realized that this symptom was common with RFCs as well.
Is there something about how governing bodies work that lead to this style of output? Why aren't we using a bit more modern techniques now, more akin to how word processors let you see the diffs inline but also the final format? Or git-style PRs that show the deltas but you can always just view "main"?