9

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

... etc.

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.

Update 21.12.2014:

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.

Improve this question
5
  • Does the solution have to be a Web application (which your tag suggest)? If not, on which operating system(s) must the solution run? – unor Dec 20 '14 at 18:17
  • 1
    It sounds like you are trying to re-invent CASE & UML and possibly tools like Rational Rose/Enterprise Architect/Software Ideas Modeler/Umbrello! – Steve Barnes Dec 20 '14 at 18:36
  • 1
    My first idea went with Steve. What kind of output do you expect: a graphical one (UML/ER diagram), structured text, …? – Izzy♦ Dec 21 '14 at 12:00
  • 2
    I updated the post so others don't need to walk through comments. I know about UML/Use Case/Workflow diagramming tools like Enterprise Architect. I don't think that's what I'm looking for. Their output tends to be great for developers, not so much for other people. Or am I missing something? I hope for a tool which can output both structured text and generate also graphical output for a quicker overview based on my input. I don't care what would be first - if I had to click through GUI to create use cases and models and output would be generated as a well structured text, I'm OK with that! – Jan Klan Dec 21 '14 at 12:22
  • Do you just want a large, complex but structured document? If so, LaTeX has been being used for that for decades. IF you want visual/graphical modelling - then I second @SteveBarnes and would recommend you look at architecture modelling tools, like Rational rose, etc. Visual Studio has a basic one I think. – Tersosauros Feb 20 '18 at 6:40
2

I would advise you about UML : it's a graphical language with different diagrams possibilities :

  • Use Case : it's diagram for customers, they could understand the way you want to develop the application
  • Class diagram : it's a diagram for coders, they could create classes and relationship
  • Sequence diagram : it's diagram for coders/customers, they could see operations and system interactions through the time.
  • others diagrams...

You'll learn how to use them in advanced way (basic seems very poor but for a big project, it's the best way to avoid coding for nothing).

You can use UMLet wich is free and very smart (and still released in 2018). StarUML is abandonware but do the job (UML is 1.4 version).

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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