Is it a good idea to keep documentation in the VCS?

Question

At work we just moved to Mercurial for our VCS from SVN.

In SVN we used to have a "docs" folder next to "trunk", in "docs" we would keep all our file documentation, client files, diagrams, mockups, etc. (we use a wiki(Redmine) for internal documentation).

Now in a DVCS enviroment we don't need a "trunk" folder, so we drop the code at the root of the repo, and now having a "docs" folder inside the repo feels weird being at the same level that the code.

This has taken me to reconsider if it is a good idea to keep those files in the VCS, we have a "documents" section in Redmine, but I have never used it because it is a pain to have to download a file each time I want to open it and I can't access the file when I'm offline.

What best practices have you guys found to manage these kind of non-code files?

Answer 1

Of course! The docs reflect the current version and may change. Have a sub directory for docs next to your source directory.

Answer 2

I don't know what type of project you're working on, but most of the large projects I've done have several different types of "source", with the user manuals and internal documentation being one of those.

I think that your old approach of keeping docs as a sibling of trunk was actually a bad one, because it meant that you'd lose the relationship between a particular version and its documentation (true, you could search the repository based on revision numbers, but what if someone was working on 2.0 docs at the time the 1.1 tag was cut?).

Answer 3

Why dont you use something like Trac to keep your docs? You can add them in "wiki-like" pages and keep it separated from your code. I've always used it with SVN, however there's a plug in for Mercurial here: http://trac.edgewall.org/wiki/TracMercurial

Maybe you should give it a try.

Answer 4

Now that you've rid yourself of the trunk folder by keeping "branches" in separate repositories (branches), you might as well have a separate branch (repository) for documentation. Since the code is not related to the documentation (i.e. changing one should not break the other), it makes sense not to store them together.

I've seen many open-source project that have separate repositories for packaging, documentation, etc and it does seem like a good way to go.

If different series of your software required different documentation, have a documentation branch for each series.