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.

Advice on writing specs

I'm the senior consultant on the technical side of a large software project, and I'm having real difficulties keeping up with my specs.

I've been working on this single project for almost a year, now. I'm writing technical specs to keep 5-6 engineers busy. The project is a web-based ERP system for a niche market, and it's getting huge and complicated. The further I get into it, the less of an overview I feel that I have. The number and complexity of interrelationships and dependencies is starting to bog my mind down, and I feel like I'm moving through molasses, working with specifications that I've written spread out in more than 30 individual Word documents, some of which have more than 50 pages. That doesn't even take into account the 50 or so functional specs that have been written by another consultant.

The longer I work on this, the harder it gets, for me, and for my developers. Because of dependencies, a developer may have to open 3 or 4 specification documents to work on a single feature, and I may have to edit 3 or 4 documents before I can assign the task to the developer.

Are there any tools better than MS Word for this kind of thing? Is it realistic for one person to manage this size of project?

Now I define some Database tables in my Database Schema document, then write technical specs (in other documents) on features that are connected to those tables. The engineer has to open up multiple docs - the only other option is to repeat stuff in multiple docs, and that's hell to maintain.

I'd like to have a tool that allows me to define things granularly and categorize them for use in different views. So, define once, use many times. Instead of opening 4 Word docs to get all the specs they need, I'd like for an engineer to be able to open a view on my specs, with all relevant info displayed. Is there anything like this out there? CMS, perhaps? I'm looking at Drupal right now. Maybe a wiki? I don't want to lose the ease of editing and formatting that Word offers, but I have to find a better way to organize these things.
anon for now
Wednesday, July 18, 2007
Rather than getting the message that your situation is screaming at you ("don't use specs to design or assign work"), you are valiantly trying to find a better way to continue doing it. I feel for you. Best of luck...
Wednesday, July 18, 2007
> ...the only other option is to repeat stuff in multiple docs, and that's hell to maintain.

LaTeX helps make this much easier, because you can define "commands" (macros) and \include{} documents in other documents. In your case, each individual spec might be either a separate document or a command. It's much more powerful than MS-Word's master document and subdocuments.
Wednesday, July 18, 2007
You could do something with saving in RTF or HTML and using M4 or CPP to hack at the text to do the inclusions.

{LaTeX would be my option, but an amazing number of software houses have MSWord as the only documentation option}
Katie Lucas
Wednesday, July 18, 2007
Me again.

Onanon - what other options would you suggest?

Also, I'll check into LaTex - I recall having heard that it was excellent at creating large documents with lots of crosslinks, but I didn't know about the commands.

Thanks for the tips. I welcome any others

Wednesday, July 18, 2007
As a programmer of a couple decades, I've never programmed based on specs, regardless of how large the project was, no one could document as fast as it was coded. It seems like a monumental waste of time. The closest I ever saw to this it still involved a great deal of verbal communication over and above the specs, relegating the specs to uselessness anyway.

So what do I suggest? Much less comprehensive specs -- just use them as a very brief overview of things. A repository for salient technical points -- just to cover your behind.
Wednesday, July 18, 2007
This sounds hairy. The fundamental problem with software is that the complexity can rise to the point where it overwhelms human understanding. At that point the system starts to be modified in a way that doesn't correctly take account of the concepts invisaged earlier. It therefore loses its conceptual coherence, and turns gradually into the "Big ball of mud" architecture.

If you're struggling as the system creator, anyone else will find the job harder. You're on your own.

My recommendations....

Get concrete.
Build some part of the system and get it working. Yes, it will be partly wrong. But it will also be partly finished, and partly specified. The biggest advantage of this is that you can test code - you can't easily test specifications. Build it, test it, and get it working. Then add features, build, test, get it working. Keep doing this until you're done. Keep tidying up the architecture as you go. Try not to go too long between working builds. By all means have a high level long term design, but go via the intermediate steps.

Try to get away from having one big design.
Bang the system into five or six (or more) parts. Specify how the interfaces of these still pretty sizeable components will work. Definitely have a high level design. But don't specify how the parts will be implemented inside. Put that on a different design - or give it to somebody else to do. Sure, you'll get some duplication. But each design stays more manageable.

Duncan Sharpe

Wednesday, July 18, 2007
I agree with Duncan. The OP said:

"The project is a web-based ERP system for a niche market, and it's getting huge and complicated. The further I get into it, the less of an overview I feel that I have."

If you do not have working software that you have put in front of the customer already, then you are in a very bad siutation, from which it will be impossible to recover without a radical change of direction (and sorry you won't be able to save face).
Wednesday, July 18, 2007
starving coder
Wednesday, July 18, 2007
Me again:

onanon: My specs are becoming less and less detailed, which I think is a good thing. I probably need to keep paring them down. One problem is that I don't work in the same office with my developers, so there's zero face-to-face communication. I just can't imagine building such a complex beast without any specs at all.

duncan: You're right. Concrete. I just spoke with my manager and told him some of the exact things you said. Have to get the current things working, tested and fixed before we take on anything new. We have already delivered some partially working features. That is, some features are "finished", but will require changes/additions when newer, interrelated features are added.

starving coder: I'll take a look at Telelogic, thanks for the link.
anon for now
Thursday, July 19, 2007
"My specs are becoming less and less detailed..."

That's a good thing indeed. I drag this out every time somebody asks about how to document something:

_____ reads _____ to learn _____ so they can _____

If you can answer that you usually know just what to write. Now if you work with the same people long enough, they'll start to know a lot of what you know and they won't need to learn near as much. You can start to talk much more abstractly and still understand what the other means.

Agile folks in small co-located teams will tell you other communication channels - face to face, gathered at a white board, etc have a much higher information bandwidth than written docs. I won't bash you for having them because some times you really do have to, but I will encourage you to tick off the alternatives before you write something new. Is there a better way for ___ to learn ___ ...

For the actual docs, I gave up on paper and even static HTML and used a Wiki. It's so easy to link from any page to any other page and follow a topic vertically through architectural layers, horizontally through similar components in the same layer, chronologically through proposals, reviews, designs or any other direction. And anybody can correct or add to it at any time. Good geek fun.
Stan James Send private email
Thursday, July 19, 2007
+1 to starving_coder.

We also use DOORS. However, it's important to keep in mind that DOORS is a requirements management system, not a document management system.

In other words, you define an individual requirement, specification or constraint. You indicate these requirements typically are grouped together, or should be associated with separate requirements over there. You track changes to each requirement or relationship. Conceptually, it's like organizing objects in object oriented programming, you'll typically have inheritances, superclasses, derived classes, abstract classes, interfaces and so on.

When the time comes, you specify... search parameters for lack of a better phrase, and the system then combines all of the relevant requirements into a single document or suite of documents. For example, your developer can ask to see everything related to a specific module, and the system will recursively grab all the specs involved, but only those specs. Management can ask to see all the high level business specs, and get precisely those.

I'm not sure DOORS is the ideal solution simply because it does take a lot of work to set up, and some organizations do find it hard to switch from the document to the database mentality. If you expect to be working on this system for another couple of years, it's worth looking into this. If your plans are to be finished sooner than that, it's a tough decision.

There are also other requirements management systems and hopefully less complicated ones. DOORS is just more or less the defacto standard for the Federal government.
Thursday, July 19, 2007
Appoint a deputy sheriff. Pick the developer with the best grasp (Not necessarily codingskills) and pull them in and give them more responsibility for subsets of the application function. Define interfaces between areas of function and put the complexity into smaller conceptual boxes. If you can't break the system out into areas of function that can be subdivided then maybe this would indicate that the design is in need of review.

Good luck.
Thursday, July 19, 2007
Me Again. Thanks for the continuing advice. A note to eclectum - I like the idea of a deputy sheriff. I actually have a senior guy who's supposed to be helping me in that role, but I've found it hard to really incorporate him into it.

One problem I have is that none of my developers (including the deputy sheriff) speak German, which is the language in which my customer writes all of his functional specs. If the functional specs were in English, I could easily pass those, along with some technical details that I add, on to my deputy. Instead, I have to play translator and technical specifier.
anon for now
Friday, July 20, 2007
To clarify - I do speak German, in addition to English, so I'm able to work with the functional specs, but they're meaningless to my development team.
anon for now
Friday, July 20, 2007
I am not surprised you are struggling. I have a similar body of specs & similar number of programmers (working off-site) in total but with specs & an application that has developed over several years.

To manage, you probably need to spend more time just managing spec updates & overall design. Push detailed implementation specs and testing to senior programmers.

To cope, all I do is talk to customers & write very high level specs. Senior programmers take the spec & write implementation/tech specs and test plans which I review. If a func spec needs to be amended then they can suggest changes which are reviewed & ammended by me.

Don't drown - if you need help (and it sounds like you are doing a heap of work), then ask for help - it maybe your project needs more design resource.
Grant Black Send private email
Sunday, July 22, 2007
"We have already delivered some partially working features. That is, some features are "finished", but will require changes/additions when newer, interrelated features are added."

Okay, this is a very good sign... continue to streamline docs and deligate control to the devs you trust. The basic job of managing is to get the most out of the skills/talents on your team; strive for oversight without micro-management.
Tuesday, July 24, 2007

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

Other recent topics Other recent topics
Powered by FogBugz