6

At the moment I am using one repository for project with the following "default" structure:

project
 - trunk
     - docs
 - branches
 - tags

I would like to know if is a good practice store the docs outside trunk folder example:

project
 - docs
 - trunk
 - branches
 - tags
Kilian Foth
  • 107,706
  • 45
  • 295
  • 310
GibboK
  • 705
  • 2
  • 8
  • 14
  • 1
    related: [Is it good to split big repository into smaller ones to have separate history/issue etc or keep it big?](http://programmers.stackexchange.com/questions/270745/is-it-good-to-split-big-repository-into-smaller-ones-to-have-separate-history-is) – gnat Feb 10 '15 at 14:42

1 Answers1

7

The (dis-)advantages of having your documentation inside the trunk of the repository depends on a number of factors. Some of the more important ones are:

  • Your branching strategy
  • How comparable the documentation lifecycle and the software lifecycle are
  • Your workflow for keeping the documentation up-to-date and the format of your documentation

If you create a new tag/branch for each release and the documentation gets released in tandem with the code, keeping the documentation inside the trunk has the advantage that it becomes easy to find the documentation that goes with a particular past release, as the documentation gets copied to the tag/branch together with the sources.

On the other hand, if your documents are released on a different cycle than the code (for example, the code gets tagged and released daily, but the documentation only once every 3 weeks), then there is no advantage to having the documentation inside trunk, as most software releases will then contain unreleased (and probably incomplete) documentation.

As a final possibility, if you regularly work on feature branches (and you are in the habit of updating the documentation as you write the code), then keeping binary documentation files inside trunk can cause you a lot of merge grief when merging the branch back to trunk. It should be noted that the fileformats used by the major wordprocessors are all binary (either proprietary or compressed XML).

Bart van Ingen Schenau
  • 71,712
  • 20
  • 110
  • 179
  • One addition: having the documentation in the trunk works, if the sources are separate. You then have the possibility to tag the state of documentation (freeze version 1.1) by creating a tag, then adding the current state of documentation to that tag. Later on, the software will be tagged as well, under the same tag, but later. We use that a lot, and that really helps. We never ever had to branch the documentation, though. – mliebelt Feb 22 '15 at 11:07