Post History

Source: https://writers.stackexchange.com/q/33535
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Using git to track modifications to the project allows contributors to include comments with each commit. If the project's guidelines, and managers' control, keeps those comments limited to a format useful for inclusion in the projects documentation - history, changelog, or users manual as the case may be, it would be nice to _link_ to the commit comments rather than retype, or copy/paste, them into the relevant documents. How do I create, and maintain, those links while also being able to select which ones are included in which documentation streams (i.e.: users manual, history, specifications, maintenance manual, etc.)?

Of note here is that while git is _known_ for software development, it _is not_ limited to that. It is equally useful for any system where multiple contributors need to coordinate, and track, their efforts. Such alternatives include a business presentation developed by a team, a textbook with multiple authors, and a research project - both data collection and reports.

* * *

### Additional information:

The git repository is always available locally, though not always on the web (such as on GitHub). As such, a method which relies on the API developed for/at a specific web host is probably not usable. Though there are some rich features available in those APIs.

The documentation itself _might_ be in a git, and often parts of it will be, though neither is a guarantee. Only the git commit comments are assured of being in the git, wherever it is hosted. The parts of the docs in a git are in markdown, however they are created. The majority of the time, the bulk of the document writing is done in a graphical word processor (MS Word, LibreOffice Writer, etc) and can be saved as either XML or RTF, though the preference is for DocBook XML format.

The tool to use is subject to change, this ability will be part of the decision process. The output formats are primarily PDF and HTML, though markdown is useful at times as well. The commit comments themselves are either reformated into the body of the documentation as a paragraph or annotation, or kept as-is (raw text) for an information bubble or footnote, depending on the target document, and the project objectives.

The key objective is to have the tool "pull" the comments into the documentation, dynamically by preference, rather than having to either retype them by hand, or copy/paste from the git to the documentation source.

Original score: 8