The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Requirements Documents

What platform / format do you use for software
requirements documents?

We did use Word. But, we like to keep things
in Subversion and it is hard to do any meaningful
diff on a raw Word document. (Plus we like to use
SVN's keyword expansions in the doc which doesn't
work with word docs.)

So, we started using RTF. Now keyword exapnsion
doesn't break the documents, but they don't always
get expanded. (Sometimes the "$Date: $" gets separated
by markup characters.) And, we still have the issue
of diffs barely being readable.

Ideally, we would like to do them in html, xml+xslt,
etc because we already convert them to PDF to make
them available on the web.

However, I don't know if we can create page breaks
with CSS so that we can include a standard header
and footer. Inside every little problem is a big
problem trying to get out...

Friday, June 17, 2005
In a previous life, we used to use Word's own versioning facility, which remembered the amendments made. And each version of document was stored in a document management system.

I've never used code source control to manage documents and I'm not sure that's such a good idea considering the freeform nature of human documentation. (I would put it like this; what's more important: getting a decent readable specification or being able to put the specifications into a source control system?)
Joel Goodwin Send private email
Friday, June 17, 2005
Joel Goodwin Send private email
Friday, June 17, 2005
I do some in Word and some in Powerpoint. Both have reasonable versioning facilities if just one person is working on it.

Otherwise, you can use Sharepoint, Subversion, CVS or even SourceSafe.
Colm O'Connor Send private email
Friday, June 17, 2005
If you're going to use Word, definitely use the change tracking features. That gives you a nice diff between revisions--much better than what 'diff' gives you, even for a text document.
Friday, June 17, 2005
Part of tracking file versions is that you shouldn't really change the file at all - information such as last change date and version should be kept separately, but made easily available.

With source code, this is easy. Instead of having the string $Date$ in your file get expanded, just use SVN to tell you what version the file is.

For documents, this isn't so convenient after they're printed. You might be able to embed the SVN keyword in a Word comment, but it's going to treat the file as binary, so that probably won't work. You could try using Word templates (autotext) to insert the SVN version number, or just give up and use Word's own versioning.

Matt Doar Send private email
Friday, June 17, 2005
You could try using LaTeX, an XML-centric document-writing system. Keep the LaTeX source in the source repository and then generate Word documents, PDFs, HTMLs, etc by running LaTeX commands on it.

I've never used LaTeX myself (and why is it stupidly cApItAlIzEd anyhow?), but I've read PDF & HTML documents that were produced from LaTeX sources, so it seems pretty decent from a user perspective.
BenjiSmith Send private email
Sunday, June 19, 2005
"I've never used LaTeX myself (and why is it stupidly cApItAlIzEd anyhow?)"

"In media where the logo cannot be precisely reproduced in running text, the word is typically given the unique capitalization LaTeX to avoid confusion with the word latex."

Sunday, June 19, 2005
Many good point. I have used LaTeX extensively
in the past 12 years. It was the first thing that
came to my mind. I am just a little uncertain about
writing the source docs in a format that only I am
familar with.

As to why SVN the docs at all - I would like to tie
specific revisions of the docs to the revision of the
code repository. It isn't just functional requirements,
it is also use case docs, etc.

Monday, June 20, 2005
We use LaTeX with a set of simple scripts for our requirements (and other) documents. Setting everything up initially took a couple of days, but now the system is in use and proving to be really valuable.

One of the reasons is that the ease of keeping revisions in control (CVS or Subversion). With a simple script the difference between two revisions of documents can be indicated either by a rule in the margin, or a different fount.

The other nice thing about LaTeX is that it is extremely easy to programmatically extract requirements from the source, for building traceability matrices etc. I'm sure guess this would be possible with Word as well, but I'm not familiar with it to comment how easy it would be. LaTeX we can also run on multiple platforms.
Monday, June 20, 2005
"I am just a little uncertain about writing the source docs in a format that only I am familar with." -Ross

I have been using LyX

for the last five years and keeping it's documents under RCS or CVS.

LyX is a GUI front end to LaTeX that should only take a little time to get used to, so could help with getting other people on the bandwagon. After getting my templates (for the kind of document, including header and footer setting) setup the documents seem to fall into place and look really good. I only rarely have to resort to LaTeX calls, and those were put in my templates so others don't have to worry about them.
Tuesday, June 28, 2005
BTW the following link shows a very nice way to include RCS/CVS information into a document using LyX/LaTeX.
Wednesday, June 29, 2005
At one of my jobs that I had, they did no requirements documentation at all.  Another used ReqPro to get the requirements out of word documents.  And today, I am at a place where they are using PowerPoint files to be specs for the website we are building.
SteveM Send private email
Thursday, June 30, 2005

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
Powered by FogBugz