I'm about to start creating a software specification for a somewhat complex web application.
I normally create a structured document describing in a very close detail:
1) Basic building blocks and their properties, for example
1a) User (name, surname, email, password)
1b) Blog post (title, text, image, posting timestamp)
1c) Comment (text, posting timestamp)
2) Internal services and headless functions allowing other parts of the system to operate, for example
2a) Cron system (allows to execute automated tasks)
2b) E-mail system (allows to create a mail queue which gets delivered by cron system)
2c) ACL mechanism (guess what?)
3) Visible modules and functions and their features, for example
3a) Registration and login (allows User [described in 1a] to register and login)
3b) Blog listing (prints out Blog posts [described in 1b])
3c) Blog post detail (allow Users [1a] open details of a Blog post [1b] and post a comment [1c])
4) Interactions and use cases, for example
4a) Registration [3a] triggers sending a confirmation email through [2b]
4b) Blog post listing [3b] can be ordered by name or posting timestamp by any visitor
So there are lots of entities, links, references and other dynamic things. At the end there is a nice document describing all the functions of the future application and so far it has worked well.
I can't get rid of a feeling that I'm trying to invent a wheel here though. The question is - is there any tool designed for creating such product specification?
I beileve if it was, it could also generate some maps of entities and their relationships and other things I'm missing here and which could be potentialy helpful to developers.
The app is intended to be a website written in PHP and Symfony framework. The goal is to have a project spec which is understandable for both customer (to approve the spec describes the app the customer wants) and developers. The customer needs it in fluent sentences with complexity added as the document continues (thus above mentioned sections 1/2/3/4 in this exact order). Customer usually does not undestand UML and has a hard time to imagine what the result will be.
Developers on the other hand do not need to read a bed time story. They need quick information about what they're supposed to create with chance to quickly discover dependencies and lookup detailed info about refered objects. That's where my so-far-successful style of writing spec failed and that's mainly the thing I'm trying to adress here.