What is the best way amonth the following to show Assumptions, Risk, Design decision section in the index.html?
1) Have seperate html pages for each of these and link them from index page
2) Have all the three as seperate sections on index page itself
Also for details related to deplyment diagram, should they be documented in index.html itself with a link to deployment diagram on it
OR have deployment diagram.html containing both deployment diagram image as well textual details related to underneath
Very basic questions but can make a difference as sun/oracle has strict guidelines about packaging.
I put my deployment diagram comments in a deployment.html along with that diagram. Similarly, for all other diagrams. I linked to the page from the index.htm. I think as long as you can get to everything from the index.html, it is fine.
I am also having only links from index.html to other diagrams. I am not adding any text for my deployment diagrams (but I do have 2 'notes' within the diagram). Also, I have made assumptions as a separate html and provided as a link from index.
There is nothing called good or best practices for this. Do what you feel is right and easy to manage.
I had one monolithic html file created using SeaMonkey. All the text-everything-links, links for diagrams, notes...every thing was cross referenced and can easy to be navigated.
I created TOC from SeaMonkey only. All my diagrams were external to this HTML and had links to the HTML. I just categorized these diagrams into separate directories.
I have provided a lot of sections - which were nothing but various level of headings. My index.html was around 950KB and overall JAR file size as 1.7 MB.