Better handle document revision histories

[johndgiese]

Auditors and regulators require that we keep a revision and approval history for our documents.

§820.40 Document controls.
Each manufacturer shall establish and maintain procedures to control all documents that are required by this part. The procedures shall provide for the following:
(a) Document approval and distribution. Each manufacturer shall designate an individual(s) to review for adequacy and approve prior to issuance all documents established to meet the requirements of this part. The approval, including the date and signature of the individual(s) approving the document, shall be documented. Documents established to meet the requirements of this part shall be available at all locations for which they are designated, used, or otherwise necessary, and all obsolete documents shall be promptly removed from all points of use or otherwise prevented from unintended use.
(b) Document changes. Changes to documents shall be reviewed and approved by an individual(s) in the same function or organization that performed the original review and approval, unless specifically designated otherwise. Approved changes shall be communicated to the appropriate personnel in a timely manner. Each manufacturer shall maintain records of changes to documents. Change records shall include a description of the change, identification of the affected documents, the signature of the approving individual(s), the approval date, and when the change becomes effective.

When using Microsoft word and excel, this process is usually handled by manually updating the revision history and revision number.

For documents stored in git, it probably makes sense to rely on git commits to track this.

Git commit messages, however, will not be accessible to non-developers. To circumvent this:

• Inside the markdown version of the files, simply link to the github history
• Inside the PDF version of the files either (1) include an appendix with a dumped version of the history or (2) generate a second document that contains the full history.

The history ideally will show line-by-line changes, who made the change, when, who approved the change, when, and when the change went into effect. To start, it probably makes sense to say that the change goes into affect once the document is approved... but it would be worth thinking about how this could be handled more flexibly in the future.

After this change, we should no longer need to manually edit the "revision number" in the YAML front-mater. That said, some people may still want to manually update this number and have it displayed in the revision history. Perhaps there is some way we can incorporate this with git tags?? It is a tricky issue.

Before implementation on this is completed, the architecture of the change should be mapped out and discussed with @johndgiese and @yujanshrestha .