1

TL;DR:

What header/footer do you put on your Functional&Technical specifications to avoid people having different versions at meetings?

Story:

We're have a lot of documents, being changed by everyone. Functional specifications, technical specifications, addendums, etcetera.

Problem is offcourse that during a meeting, after an hour someone notices their printed version differs from someone else's.

I thought this could be solved by forcing everyone to use the same header/footer on each document:

Header

  • Project concerned
  • Document title (center aligned)
  • Document author (right aligned)

Footer

  • Last modification date
  • Date on which document was printed
  • Full document path and name (which always include the version number)
  • Page X of Y

This way, we could all easily check the filename and last modification date before starting the meeting, and make sure everyone has the same copy and is talking about the same document.

Would this work? Am I missing something? What do you guys use for your specifications to avoid versioning problems?

Improve this question
7
  • What the heck is TL;DR: by the way?
    – Jose Faeti
    Sep 7, 2011 at 16:18
  • 2
    TL;DR stands for "too long; didn't read". It's either a response to a post saying "way too long, man - summarize it" or to highlight a summary section of a post.
    – Thomas Owens ♦
    Sep 7, 2011 at 16:21
  • Correct :) The professional phrase to use in the documents you send to management would be "management summary", but amongst programmers, TL;DR conveys the message perfectly.
    – Konerak
    Sep 7, 2011 at 16:45
  • 3
    I prefer "Short Version" or "Summary" over TL;DR. Just sayin'.
    – Robert Harvey
    Sep 7, 2011 at 16:47
  • @Thomas: cool, didn't know that! thanks :)
    – Jose Faeti
    Sep 7, 2011 at 16:56

4 Answers 4

Reset to default
2

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.

Improve this answer
4
  • This is a very informative post, thanks. Our documents have a similar structure, but every so often someone makes a change without updating a minor version number - so I thought (hoped?) relying on a (supplementary?) "last modified" date was more foolproof.
    – Konerak
    Sep 7, 2011 at 17:28
  • When it comes to changes, tracking dates/times/logs in a version control tool as well as the document might be helpful. However, nothing beats having discipline even under tight deadlines and external pressures. Mistakes happen, but the only thing you can do is try to prevent them at every step of the way through careful execution of a plan.
    – Thomas Owens ♦
    Sep 7, 2011 at 17:32
  • So, using (Microsoft) sharepoint, you can do a diff between two (Microsoft) word documents?
    – Konerak
    Sep 7, 2011 at 17:48
  • @Konerak No, and if I implied that somewhere, please point it out. You can view the history of a document (including "commit log" style notes) and view old versions. We typically use revision tracking and notes to handle diffs, although I understand the newest version of Office supports some kind of diff functionality.
    – Thomas Owens ♦
    Sep 7, 2011 at 17:51
0

What header/footer do you put on your Functional&Technical specifications to avoid people having different versions at meetings?

We do not have a standard set in stone accoss projects, but something like this will be a good minimum:

  • project
  • subsection of project
  • creator
  • create datetime
  • last modified by
  • last modified datetime

Even better is to check specifications and design documents into source control (Sharepoint does a lot of the same things if it is easier for business people). Souce control will log all of the stuff above, plus keep a history of all of the changes. Also, I would recommend forcing comments with check ins. Meaningful comments on changesets can be a huge help if checkins happen frequently from lots of people. Basically, just treat the spec like a part of the project (because it is).

Improve this answer
6
  • I'd love having specs under source control, but one of the biggest gains (diff between versions) is kind of hard, depending on the format of your specs. Usually MS Word is used in our organisation, so a diff won't reveal much. Not that I believe that a Latex diff output would be that much more readable, but still. A commit log would help, though. MS Word does have its built-in "reviews" which has its uses.
    – Konerak
    Sep 7, 2011 at 16:47
  • diffs are nice, but you could always ignore that feature. Source control could probably easily handle your other problems. Also, I know a lot of people do not like sharepoint, but it basically has a full fledged source control based around Office formatted documents, that is easy to use for business people. It has checkouts, changelogs, and all sorts of logging/metrics.
    – Morgan Herlocker
    Sep 7, 2011 at 16:54
  • @ironcode: do you mean version control? Specifications and design documents have nothing to do in a source control.
    – Arseni Mourzenko
    Sep 7, 2011 at 16:57
  • @MainMa - from wikipedia: "Revision control, also known as version control or source control (and an aspect of software configuration management or SCM), is the management of changes to documents, programs, and other information stored as computer files"
    – Morgan Herlocker
    Sep 7, 2011 at 16:59
  • @ironcode: well, the fact is, the two terms have a different meaning, and you're using them wrong. See stackoverflow.com/questions/1056912/… and thedailywtf.com/Articles/Source-Control-Done-Right.aspx "Revision Control -vs- Source Control".
    – Arseni Mourzenko
    Sep 7, 2011 at 17:09
0

Don't show too much information at the top and the bottom of every page. It brings nothing but distraction.

In general, you put on every page the page number, the document title (including, optionally, the name of the project), and that's pretty all. If the document is long (read more than thirty pages), you may also include the chapter/part, but this has a problem when the document is maintained by the people without much technical background: they usually don't know how to do this properly in text editing programs they use.

Don't use version number neither. Some people have no problems with this. Others, like me, are completely unable to remember to update the version number in a header when they update the document.

What you can do to make it easier to manage different versions (and what is done by many companies from what I've seen) is to put on the first page the list of document revisions, with date, author name and a summary of changes.

There are two other things you can do, but they are less related to the document, and more to the people and the organization of the meeting:

  1. Before the meeting, ask everyone if they have downloaded the latest version of the document. Saying "remember, the document was updated yesterday evening" may help people figuring out that they may have forgotten to check for the latest version.

  2. Don't print documents. If inside your company, everyone or nearly everyone has a notebook, why would they have a paper version of the document? Why would they reprint it again and again at every revision? A twenty pages document with thirty revisions printed by fifteen people in the team can have a big cost, both for your company and for the environment.
    If you don't have enough laptops, investing in a large screen or a projector for your meeting room can be a good alternative (even if one document per person is much more comfortable).

Improve this answer
0

I use this convention:

  • Documents are always checked into a subversion repository. They don't have the version in their name, so that there is a clear revision history in subversion, and so that they have a permanent https://subversionserver/path-to-document URL that can be shared with people.
  • The first page of the document contains a table describing each version with version number, author, summary of change, and date of change. Whenever someone modifies the document they add a line on the cover page and commit the file.
  • Subversion locking is used to prevent concurrent edits.
  • Documents tend to outlive the document storage systems they are kept in, so the document must contain its own complete history.
Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.