After writing a specification for around a month now, I'm afraid I'm lost in a semantic, often pedantic, wonderland. I'm trying to create something like a W3C Recommendation, but hopefully more palatable and only for use with my own application.
I'm trying to decide on the wording or language to use when writing a functional specification for a web based application.
Please comment or make a suggestion so I know I'm on the right track.
Here's the abstract:
Here's the Quick Table of Contents:Quote:
This specification defines how the Ragsdale Site Manager (RSM) will function entirely from the user's perspective. RSM is a web based application that provides a person or group with the functionality to manage text based content in a web site. This specification describes features, screens, menus, messages, and so on. Implementation (data structures, relational database models, choice of programming languages, algorithms, etc.) and graphic design details are avoided.
A full explanation of RSM is provided in "What is RSM?"Quote:
1. What is RSM?
2. Definitions and Terms
3. Character Sketches
4. Base Functionality
5. Plugin Functionality
6. Content Markup
7. Theme Markup
A. References
I chose to use the term "screen" rather than "page." I use the following definition:
The term "page" suggests the web site's content, that my application manages, and not some functionality in my application. I describe content as a "submission."Quote:
A screen is what a user views with when he or she is using the application. In a graphical web browser, a screen is the area inside the browser window.
I use character sketches because I want to envoke some emotion rather than rely on dry generalized descriptions of users' needs.
Here's an example:
The following are some examples from "Base Functionality." I tried to simulate my formatting with BBCode.Quote:
Grace and John
Grace is a retired mother of three and grandmother of six. She's 68 years old and most of her time is spent between her grandchildren and renovating an investment property she and her husband John recently bought. John is 70 years old, retired, and Grace makes sure he has plenty to do.
John is fairly knowledgeable in computers, but Grace can hardly use a mouse. Neither of them could care less about technologies such as CSS and XHTML, they use Internet Explorer on Windows, and they have a slow 56k dial-up Internet connection. Grace and John know a lot about home improvement and want to start a tutorial web site to help others.
Quote:
4.1.1. Base Screen
This screen is an alias to a category or submission and the default screen a user views.
This screen is displayed if the user does not request a category or submission.
A member with appropriate authority sets this screen to be an alias to a category or submission. For example, in William's site, he has several categories: News, About, Blues, Classic Rock, Jazz, R&B/Soul, and Rock. In the About category, he has the submissions "Site History," "Site Creator," and "Conduct Code." He might set this screen as the News category or "Site History" submission.
Quote:
4.1.2. Category Screen
This screen lists sub categories and submissions under the requested category.
Depending on the user's authority, one or more of the following selections are displayed:
Add Sub Category
See: Category Addition Screen
Add Submission
See: Submission Addition Screen
Delete
See: Category Deletion Screen
Update
See: Category Update Screen
Set As Base Screen
See: Base Screen
There is no limit to the number of sub categories.
The following content elements are displayed for each sub category:
Title
The title of the sub category.
Description
The description of the sub category.
Submissions
The number of submissions under the sub category.
Title is required. All other elements are optional. A member with appropriate authority sets the elements to be displayed in the Category Addition Screen or Category Update Screen.
The user selects Title to view a sub category.
Sub categories are ordered by Title ascending (A to Z).
A member with appropriate authority sets the maximum number of submissions per screen in the Category Addition Screen or Category Update Screen. If the number of submissions is greater than the maximum number per screen, this screen is split into multiple screens. The user selects which screen to view by selecting "Previous," "Next," or the screen number. For example, if this screen is split into 5 screens, the user has the selections: Previous, Next, 1, 2, 3, 4, 5
The following content elements are displayed for each submission:
Title
The title of the submission.
Author
The author of the submission.
Date
The date the submission was added.
Description
The description of the submission.
Responses
The number of responses to the submission.
Title and Description are required. All other elements are optional. A member with appropriate authority sets the elements to be displayed in the Category Addition Screen or Category Update Screen.
The user selects Title to view a submission.
Submissions are ordered by Date ascending (newest to oldest).
Quote:
4.1.3. Category Addition Screen
This screen has a form which is used to add a category.
The form has the following form fields:
Title
The title of the category.
Description
The description of the category.
Sortable
If selected, the category is sortable by the user.
Display Sub Category Descriptions.
If selected, display the description of each sub category.
Display Submission Authors
If selected, display the author of each submission.
Display Submission Dates
If selected, display the date for each submission.
Display Submission Responses
If selected, display the number of responses for each submission.
Title and Description are required. All other fields are optional. If the user selects Sortable, the Category Sortable Screen, rather than the Category Screen, will be displayed for the category added.
When the user submits the form, the following tests are performed on the server:
- If Title or Description is empty, display the error message "x is required." Replace x with the name of the field.
- If any field, with the exception of Description, is greater than 250 characters, display the error message "x must be less than 250 characters."
- If Description is greater than 500 characters, display the error message "Description must be less than 500 characters."
If the form has errors, this screen is redisplayed. If any fields have been filled in, they're pre-populated.
If the form has no errors, the data entered in this screen is stored, and the user is redirected to the Category Screen or Category Sortable Screen for the category added.
