Model documentation question

General Questions/Discussions
1

Hi:

I have to produce a “developer’s guide” for a java web application I developed and I want to use VP. This document has to contain everything a developer should know about the application in order to successfully make changes to it, fix bugs etc. Now, In my ideal world I would define all the artifacts of the application in a VP model and then generate the word document from VP. However, I am struggling with the representation in a VP model of certain sections I want to produce. I find that diagrams are too dry and at times it is needed to add more explanations. Here are a few things I want to add to the document:

  • I want to add little cookbooks - that describe what to do if you want to add a new page or a new screen. How do I represent such sections with explanations within a diagram and have them generated as text in a word document?
  • I want to describe the data access layer and what to do when you want to run stored procedures. As a matter of fact I want to describe all the layers.
  • for different sections I want to provide information that would allow the reader to find out more details. For instance, I would provide queries that allow the reader to view the data that is relevant to specific section.

I currently find the word document that VP generates a bit dry. I see this developer’s guide as mind-mapping diagram that allows the user to drill down into different sections and where different sections relate to each other. But when the vp model is generated into a word document the interactive aspect of a vp diagram that allows you to reference and link together diagrams seems to be lost (I played briefly with the settings but I haven’t discovered yet a way to make the diagrams interactive within the word document - that is click on an image and jump to another diagram or section within the word document).

I also noticed that the text sections are generated as images which is undesirable.

So, right now I don’t know exactly how to start this. Well, actually, I started writing the document manually and insert diagrams from VP. But I have this feeling that I should be able to add all I need in a VP model and then generate the document from it.

Any suggestions, pointers to documentation would be appreciated.

Thanks