Keep safe your project's documents

  It is generally believed that the only valuable set of files for a given project are the source code files. In general, programmers will talk to you about keeping it safe in a version and source control system (VCS), usually named CVS or SVN repository. The truth is that the documents that are part of a project are important as well.

  Just think what would happen if you would lose the user guide, the installation guide, or the Client contract latest version. Indeed, the value of keeping this kind of documents in a source control system is less than keeping the source code files: while you may have text based comparison tools available for comparing two versions of a source code file, you usually don't have such tools available for comparing two versions of an Office Word document.

  Still, it is good practice to keep the Office document on the source control system, as you will make sure that you will not lose that content and it will also keep a file history on hand, with review notes, and with the possibility of manually comparing between different document versions.

  From technical point of view, when we talk about versioning the contents of a document, due to VCS way of working for you, you have to keep the same filename between different updates. That means that a document entitled "User guide" will remain named like that no matter if it is version 1.0 or version 2.0; otherwise said, it is wrong to name them "User guide v1.0" and "User guide v2.0", as this will lead to independent files on VCS, with no history whatsoever. Still, you would like to use some version information available for the Client or for your own internal needs. The satisfying solution is to use the version information somewhere inside the document content itself, like on the first or second page of a Word document. By doing so, you can provide information, for the people using the contents, about which version they are working with, while also keeping the same filename for VCS history handling features.