Program visualization

Question

I'm starting with a web project and I would like to write its functionality and features on a "piece of paper" like professionals do. I have to prepare the documentation for the project with all information about the

• purpose and project overview,
• database structure,
• MVC and REST functionality (model, view, controller),
• website and widget layouts and functionality,
• client/server communications.

What I would like to prepare is a proposal for a project where I explain the idea and the exact solution and how to carry it out with all the details.

How do I prepare this? What do I need? Can you show me an example?

Answer 1

Professionals focus on the audience. What is the purpose of this document, the story it needs to tell? Writing takes time, and that has to balanced with other ways to spend your time.

Do you have to sell the project to a customer? Or to management? Investors? Or to your co-developers? Or is it mostly for yourself?

The level of detail is going to be very different. The presentation is also going to be very different, both in form and in presentation order.

Is it sufficient to just make a few snapshots of white-board discussions or brown paper sessions, or do you need a glossy brochure, video and powerpoint?

For a web project you might want to put it all in a wiki.

[edit] If you have two different kinds of public, you might want to create separate documents, or at least provide a management summary. Focus on the business for the management summary, and put the nice technological advantages in the parts your co-developers read.

Answer 2

Separate requirements from implementation. I would get an initial document out capturing the "what" of the system.

Document the Web Site - I use state diagrams for that. Each page is a state, each possible navigation/action is a transition. Depending upon your exact audience you may need to mockup the screens so the transitions can be understood.

Detailed Design of the pages and templates is somewhat secondary - I like to keep this back becuase it tends to be the piece where everybody wants to be a designer.

If the system's interface also includes an externally callable Web Service (perhaps REST) then document that it's part of the external interface and needs to be agreed by the people using it. Simple UML class diagram or pseudo-code interface.

There will be an "Interface data Model" associated with these artefacts. The data displayed on the plages and returned by any public nservices. This can be modelled in your choice of data modeling tool (I would use UML class diagrams).

The on to designing ... MVC layer and detailed busines logic can be modelled using OO techniques, again UML works fine.

Peristence layer ... depends upon if database/legacy system already exists. You'll need some kind of a data model here and may well need to document mapping between Interface Data and Peristed Data - this can be trivial or may need very detailed design. Capturing mapping data may be best done in tables or spreadsheet-like tools.

Answer 3

I would advise you to write two documents :

• One technical description : Where you'll write all the technical stuff, from the database structure to the protocols description if needed.

• One functionnal description : Where you'll write all the functionnal stuff, from the purpose of the project, to the description of each functionnality of your application.

Each document will target different people, some being very good with technical details and others being very good with app usability.

When I want to be sure that my technical and functionnal documents are useful, I write them thinking "If I die tomorrow, I want the people who read these docs to understand the app in every way, and I want them to be sure how to do it, just like I would like it to be done". I eventually end up going deep in the application details, but it's usually a good idea. I noticed that the more time I spend writing these docs, the less phonecalls I get later, and the less bad surprises I get once the app enters the testing stage.

Cliffnotes : Two docs targetting two very different audiences. One being very interested by technicals tidbits, and the other having no knowledge about technical tidbits. Take your time, explain things, make schemas and diagrams (if you are sure you are good at these), read your docs again and again, and you'll have a solid documentation.

Edit: Word (or any alternative word processor) is usually good enough to make that kind of documents. Using UML is not always a good idea, especially if you're not good at UML (no shame in it :).

One little trick I find useful : Using a WYSIWYG web-pages editor can help you make quick-and-dirty pages prototypes, that you can insert into your docs. I even went as far as re-installing VB6 on an old computer, to make a quick-and-dirty windowed app prototype for that purpose. It works great and takes very little time.