9

I simply cannot imagine writing software without a spec. No matter how sketchy or high level it is, spec is important to explain to the clueless programmers on what are the functionalities of the program.

But the problem with spec is that it is somewhat a second class citizen in the whole software development cycle; when the development picks up the steam, it is neglected. But when dispute arises, the developers and testers and sales will scramble to find the spec to justify their grounds.

Either one or more scenarios will happen:

  1. The spec cannot be recovered, no one knows where is the spec
  2. Different versions of the spec emerge from different sources; it takes great difficulties to find out which version is the latest version, or whether there is a latest version available.
  3. The spec is incomplete, some parts of the documents it refers to are missing.

So spec management is important, and it's equally important that everyone has only One Single Source of Spec.

How do you manage your specs? I tried to get everyone to use Google Docs but everyone objected. Everyone is just too attached and enamored with Microsoft Word, which is-- in their opinion-- very easy to use, very easy to insert image, very easy to type equation and whatnot.

How to convince them that MS Word is just terrible for sharing?

Graviton
  • 4,005

5 Answers5

6

How to convince them that MS Word is just terrible for sharing?

Don't waste your time.

First. Spec should be in plain text (really) and under source code control. Use Markdown or RST or some other lightweight markup tool to produce a PDF or HTML page. Plain text.

Second. Take the various sources. Merge them. Write your own final document.

When they object, they have two choices.

  1. Use Google Docs (or the source code control tool) to edit your version.

  2. Continue to send you changes which you edit, filter and morph into the final document.

I prefer #2. Someone needs to "own" the spec. And a bunch of folks (wiki-style) leads to debates and change-wars and side-documents and off-line conversations and the like.

S.Lott
  • 45,390
6

I don't think it is a "tool" issue but rather a "process" (or lack of process) issue.

You probably already have a process to release software (unit test, integration test, release letter, delivery, etc), you need to implement a documentation process as well.

  • Who is going to write the specs ? Who is going to update or maintain them ?
  • Who is going to review the specs ?
  • Who is going to approve the specs ? Architect, Project leader, QA?
  • How the specs are stored ?
  • Who is going to make sure that no obsolete versions are used ?
Xavier T.
  • 1,612
  • 2
    +1: tool problems are often symptoms of process problems. – S.Lott Jan 27 '11 at 15:33
  • we do have a process but people just love to complain that the process doesn't work and cut corners whenever possible. – Graviton Jan 28 '11 at 00:45
  • @Graviton : your main problem is probably that management can't see the use of documentation and thus, don't enforce strict rules. If you want things to improve, you 'll probably have to show them how important it is. – Xavier T. Jan 28 '11 at 08:55
4

Some kind of control is definetly required.

It needs to be versioned, and signed off, and this process needs to be strict.

In too many places, sign off is neglected, and this leads to bun fights.

The location doesn't matter so long as it can be tracked

  • Sharepoint
  • a secure, backed up shared drive
  • I've seen some places use their code source control!!

But more importantantly you need buy in from all involved and 1 or 2 people who's responsiblity it is to manage both the document AND the sign off eg. the Project Manager.

ozz
  • 8,322
  • 2
  • 30
  • 62
  • +1, I strongly suggest moving the spec doc in to source control if nothing else helps. One advantage is you get version history. Even if you can't do version diffs (unless you find a plugin that can do diffs on Word files) you can still extract all version and see what's changed. This can be VERY useful in a dispute over specs. The sign-off is also very good to have. And also the importance of having everyone involved in the process (so no one can say "when was that decided?") can't be stressed enough. – FrustratedWithFormsDesigner Jan 27 '11 at 16:12
0
 > How to convince them that MS Word is just terrible for sharing?

you cannot easily compare what-s the difference of two instances in a version-control-system.

I dont-t like word specs for that reason. But since it-s a political decision to use word-specs we have as first page "history informations" with these colums:

version-number(relates to product-verision), author, date, description

k3b
  • 7,528
0

MS Word is perfectly fine for creating a spec. We manage ours in SharePoint, which also handles the versioning. If you don't have SharePoint or another document management product handy, Google Docs is OK (you can now upload .doc/.docx files without converting them to Google Docs format). Or as others have suggested, you can even store them in your source code version control system (if the people creating the specs have access to that system).

Marcie
  • 2,999