Where should functional specs be stored and how should their revision history be tracked?

Question

Background

I come from a hardware development engineering background. Our detailed specifications contained a revision history as a table at the end or beginning of the—typically MS Word—document. These specs were saved in a document management system separate from the management system used to store the hardware design deliverables, such as the schematics and board layout files. Sometimes a document management system wasn't used for the specs and instead the filename contained the doc revision number. This always felt like a suboptimal solution given that someone would start modifying a doc with a downlevel revision.

Questions

I've started working on a software project that is using DVCS (Git), and am planning to write the specs/docs as text files using Markdown, instead of MS Word docs. I like the idea of having everything in the DVCS, including the specs and user documentation. However, it seems like the specs and documentation should not be stored in the same repository as the actual code. This leads me to my questions:

1. Should specs/docs be stored in a separate repository from the code?
2. Should there be a separate repository for each spec/doc?
3. Do software engineers/coders normally put a revision history in their specs and documents given that the DVCS provides the ability to have a revision history?

Answer 1

In the corporate world, 1. and 2. depends on your repository's ability to handle the security model required for creating/accessing/approving the documents and code. For 3. when applicable, you should always include in your documents the in-depth reasoning behind the revision.

Answer 2

1. Don't store the specs in some obscure format that isn't widely available. The tool should not dictate the form of the document. The documents may need to be used by someone outside your group who is only familar with word.

2. Yes, the specs/docs should be stored in a separate repository from the code. Managing a code repository has different requirements than a document repository. You can use the same parallel organization structure (i.e. same project names, hierarchy etc.) in the document repository, which should make it easy enough to find the relevant documents.

3. There should not be a separate repository for each spec/doc. The organization should reflect the organization of the code repository. Do you have a separate repository for every code file in every project?

4. Yes, it is common to put a revision history in the specs/documents regardless of the repository. Documents may need to be used across organizations, and people outside the organization may not have access to the source control but may still need to make changes (which someone in your organization can manage/check in).

More commonly, often the documents need to be used across different company departments (i.e. reviewed by the UI team, sales, marketing who don't have access to/familiarity with repositories).