File and HTML Structure for Requirements Spec Document

File and HTML Structure
for the CSC 308 Requirements Specification Document

A detailed file structure for the requirements project directory is shown in Figure 1.

Figure 1: Requirements directory file structure.

The .html files correspond to the document sections and subsections described in the handout on the requirements specification document outline. The index.html file contains a hyper-linked table of contents for the complete requirements document. The files intro.html, functional.html, non-functional.html, developer- overview.hmtl, formal-spec.html, and rationale.html contain sections 1 through 6 respectively of the requirements specification document. The ui-overview.html file contains section 2.1. The files with names in italics in Figure 1, with the prefix functional ..., contain subsections 2.2 through 2.n of the document, with additional files as appropriate for subsubsections, e.g., 2.4.3. The rule of thumb for when a scenario sub(...)subsection should be in a separate file is if it contains more than 7+/2 screen pictures.

Within the HTML requirements files, there is a hypertext linking structure, which is shown in Figure 2.

Figure 2: Requirements document hyperlink structure.

This is the structure defined by the HTML href links within the various document files. The top-level index has a complete set of links to all sections and sub(...sub)sections of the document. The functional section has links to its immediate subsections only. Each functional subsection in turn has links to its own immediate subsubsections. Note that it is likely that three levels of document depth should be sufficient for all 308 requirements, however if you need to go deeper that's fine.

The complete hyperlink interconnectivity is based on the section and subsection hierarchy. Specifically, each document file at the same level has "next" and "previous" links to its siblings on that level. Each document file also has an "up" link to the document file at the next level up. Finally, each document file has a "top" link to the index file, except for the index file itself. For an example of how the links appear in a document, see the online Milestone 2 example in http://www.csc.calpoly.edu/~gfisher/classes/308/examples/milestone2. There are a number of online resources for learning about HTML. For example, the HTML Writers Guild resources page at http://www.hwg.org/resources/html has useful information and links.

In CSC 308 you will need to understand raw HTML well enough to assemble a large multi-file document, authored by five or six team members. You may use a word processor, such as Microsoft Word, to create individual document files, but some work with raw HTML will be necessary to create the complete document. Many people, including your instructor, create raw markup documents directly, without using a word processor. The advantage of editing the markup yourself is that it creates much more readable HTML files than those typically generated by a word processor.