Ttdfjt

My rule is that when I clone a repository and press a “build” button, then, after a while, everything is built. To achieve this for your generated documentation, you have two choices: either someone is responsible for creating these docs and putting them into git, or you document exactly what software I need on my development machine, and you make sure that pressing the “build” button builds all the documentation on my machine.

In the case of generated documentation, where any single change that I make to a header file should change the documentation, doing this on each developer’s machine is better, because I want correct documentation all the time, not only when someone has updated it. There are other situations where generating something might be time consuming, complicated, require software for which you have only one license, etc. In that case, giving one person the responsibility to put things into git is better.

@Curt Simpson: Having all the software requirements documented is a lot better than I have seen in many places.

These files should not be checked in because the data to generate them is already present. You do not want to store data twice (DRY).

If you have an CI system, you could perhaps make that build the docs and store them for that build/publish it to a web server.

One advantage of having them in some repository (either the same or a different one, preferably automatically generated) is that then you can see all the changes to the documentation. Sometimes those diffs are easier to read than the diffs to the source code (specifically if you only care about specification changes, not implementation one).

But in most cases having them in source control is not needed, as the other answers explained.

Ignored. You'll want to have the repo's users be able to rebuild them anyway, and it removes the complexity of being sure the doc's are always in sync. There's no reason not to have the built artifacts bundled up in one place if you want to have everything in one place and not have to build anything. However source repos are not really a good place to do this though as complexity there hurts more than most places.

It depends on your deployment process. But committing generated files into a repository is an exception and should be avoided, if possible. If you can answer both of the following questions with Yes, checking in your docs might be a valid option:

• Are the docs a requirement for production?


• Does your deployment system lack the necessary tools to build the docs?

If these conditions are true, you are probably deploying with a legacy system or a system with special security constrains. As an alternative, you could commit the generated files into a release branch and keep the master branch clean.

It depends. If those docs:

• Needs to be part of the repository, like the readme.md, then it's preferred to keep them in the git repo. Because it can be tricky to handle those situations on a automated way.




• If you don't have an automated way to build and update them, like a CI system, and it is intended to be seen for the general audience, then is preferred to keep them in the git repo.




• Takes A LOT of time to build them, then is justifiable to keep them.




• Are intended to be seen for the general audience (like the user manual), and it takes a considerable time to build, while your previous docs becomes inaccessible (offline), then is justifiable to keep them in the git repo.




• Are intended to be seen for the general audience and has to show a history of its changes/evolution, it could be easier to keep previous doc versions commited and build/commit the new one linked to the previous. Justifiable.




• Has an specific accepted reason for all the team to be commited, then is justifiable to keep them in the git repo. (We don't know your context, you & your team do)

In any other scenario, it should be safely ignored.

However, if its justifiable to keep them in the git repo, could be a sign of another bigger issue that your team is facing. (Not having a CI system or similar, horrible performance issues, facing downtime while building, etc.)

As a principle of version control, only "primary objects" should be stored in a repository, not "derived objects".

There are exceptions to the rule: namely, when there are consumers of the repository who require the derived objects, and are reasonably expected not to have the required tools to generate them. Other considerations weigh in, like is the amount of material unwieldy? (Would it be better for the project just get all the users to have the tools?)

An extreme example of this is a project that implements a rare programming language whose compiler is written in that language itself (well known examples include Ocaml or Haskell). If only the compiler source code is in the repository, nobody can build it; they don't have a compiled version of the compiler that they can run on the virtual machine, so that they can compile that compiler's source code. Moreover, the latest features of the language are immediately used in the compiler source itself, so that close to the latest version of the compiler is always required to build it: a month old compiler executable obtained separately will not compile the current code because the code uses language features that didn't exist a month ago. In this situation, the compiled version of the compiler almost certainly has to be checked into the repository and kept up-to-date.