Technical Specifications vs Design Documents – Key Differences

We've got plenty of that at my last place of work.

The product managers have chosen to use the present tense to describe what must be done, like:

The user sends an order. The system sends a confirmation message.

Unfortunately the description of the preconditions was also done in the present tense, like:

The user puts an item into the shopping cart and specifies the quantity.

This has caused a lot of confusion for me since it is not clear what already is and what is yet to come. I've tried to make them use any sort of a future tense but they never got to change. Personally, I couldn't get used to it in all my two years there. It just doesn't make any sense, sound like somebody hasn't got a mastery of the languages tenses.

Therefore:

• Use a present tense for what already exists

• Use a future tense for what must be done. Employ the worlds "should", "must", "will".

The best way to manage document control is to have a clear and well documented configuration management policy. This policy should address versioning of everything related to the project, from external libraries to code to documentation. In the same location, you can also address change management - how you deal with changes to any aspect of the project, from requirements through your code.

The key is to have some kind of system to track changes and revisions. At work, we use SharePoint. You could probably get away with using any version control system, but you are

You probably keep code in a version control system. The idea is that you do the same with documents, although you probably want to enable locking for documents since merging binary files (Word Documents and so on) might not be possible.

The official versioned document should be kept on the corporate intranet or someplace with appropriate security and access control. At work, we use SharePoint, which handles versioning as well. If you use some other technology or tools, you might be able to leverage that (perhaps with plugins or extensions). Just make sure everyone knows where to go to find the latest and greatest official documentation.

It's also necessary to keep track of not only the current version identifier, but also a revision history, inside the document. This way, when you print the document, it becomes easy to "diff" them and figure out what sections have been modified between any two physical copies.

Just to describe what, specifically, our documents look like:

The first page is a cover page. The corporate or project logo is in the top left corner. The document ID, late modified date, and revision ID are in the top left corner. Classification markings are centered in the header and footer. The document title is roughly centered on the page. Below the title comes all applicable copyright and distribution notices.

On all other pages, the header contains classification markings in the center and the document name in the right corner. The footer contains the document ID and revision ID in the left corner, the classification markings in the center, and the page number in the right.

The next page is the approval sign off page. It contains the document title and ID number, along with the signatures and dates of the preparer and approvers. On official versioned copies, the document actually has an image with the signatures in it.

The third page is the revision record, which again as the document title and ID, followed by a table that provides a revision ID (usually a letter), any change requests associated with the revision for tracking back to defect reports (yes - we file defects against documents), the date of the revisions, and the pages/sections modified.