1

I have compiled the technical documentation for a physical product. It includes documents like user manuals, technical descriptions, maintenance instructions, etc. I have decided that all these documents should be collected in PDF format in one single directory. The corresponding original files (in Word, Excel, or other formats) are stored elsewhere and there is an Excel sheet that assigns an original document to each PDF.

The collection of PDFs will be subject to change, i.e., PDFs will be added, removed, or replaced by other versions. I am thinking of using Git for tracking these changes and being able to revert back to previous versions.

I am aware that Git is not intended to be used primarily with binary files, as it cannot track changes inside documents if they are in binary format. This means that between different commits, there will just be different PDF documents stored, and no in-file differences. This also means that the repository size will be larger than with a text-file-based approach, which I am willing to accept.

I am also aware that there exist document management systems that are better suited for this task. The main reason I want to use Git is that I already know the tool.

Are there any reasons that I am not aware of why using Git for this task would be an unwise idea?

2
  • 2
    While what you ask is related to writing (just as programming a writing app or buying a desk are related to writing), but you will get better answers on a site that is dedicated to software recommendations (e.g. softwarerecs.stackexchange.com) or frequented by users that use version control systems (e.g. softwareengineering.stackexchange.com). Both of the mentioned sites have many questions about version control solutions, e.g. softwarerecs.stackexchange.com/q/42428
    – Ben
    Mar 1 at 12:48
  • @Ben: Thank you for your helpful reply. I consciously decided against posting the question to softwareengineering because it is explicitly not about software documentation. However, I didn't know softwarerecs, which I agree now is the better place for this question. I will move the question there. Thanks for showing me!
    – Dave
    Mar 1 at 14:08

2 Answers 2

1

You may want to consider checking out Google Docs, as I believe they offer version tracking. While I have heard of it, I have never personally used this feature. As a developer by trade, I enjoy writing.

1

If you don’t have access to a tool to effectively diff the pdfs I imagine this approach will be suboptimal. Especially considering you have the original MS files, which are text -- the extensions ending with an 'x' are xml based. This means you can use word as the diff tool -- a configuration element in the git configuration file.

Then export the pdfs as part of publishing the documentation to your users.

Keeping the source files out of source control while keeping the output files under source control seems backwards and seems very much to complicate maintenance and revising processes. But, if you have a good pdf diff tool, then its a don't care since you can roundtrip the pdf back to the MS file if you ever need to -- like because you lost the original files because they weren't under source control.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.