Class, this is a spec that I wrote for designing the website mathingo.com http://www.mathingo.com/ This would be the bare minimum that I would expect your spec to look like. Obviously it will change dramatically given that your sites are much different, but you should have details like this and a full discussion of all of the different pages that you will have on your site. You may want to look at other sites similar to yours to see what types of pages they have to include on their site as well. Math Bingo Functional Specification Sean and Sylvia Forman Updated November 11, 2003 Updated January 27, 2004 Copyright, Forman Math Productions and Saint Joseph's University, 2004. ---------------------------------------------------------------------- Overview ---------------------------------------------------------------------- Mathingo.com (combination of math and bingo) is a teaching utility designed to help math teachers at a variety of levels create interesting classroom activities. This application will create bingo cards and keys usable in a classroom setting for any number of students and for a variety of mathematical abilities. ---------------------------------------------------------------------- Scenarios ---------------------------------------------------------------------- Scenario 1: Dr. Jones-Smith Dr. Joe Jones-Smith teaches calculus at a small liberal arts college in the pacific northwest. On his way into work with his black lab, Rufus, he picks up a caramel macchiatto at the local Jumpin' Java House. As he is pulling out of the parking lot, Rufus begins licking at the whipped cream spilling over the lid of the macchiatto. Joe reaches for the drink, but knocks it over spilling it onto his laptop containing his lecture notes on the chain rule. The laptop fizzles and pops. When he arrives at the office, Joe finds that his lecture is lost and he has only 30 minutes until the students arrive for class. Realizing he could review the power and multiplication rule for today, he goes to the departmental computing lab, logs onto Mathingo.com and generates a set of 20 bingo cards covering the power rule. Class is saved. Scenario 2: Dr. Carlos Floon Dr. Floon is finishing up the second chapter in his calculus textbook a little earlier than expected, but rather than move the test up, he wants to spend an extra day reviewing the material. He decided that playing bingo in class will be an appropriate way to do this. He goes to google and types in "math bingo". The first site that comes up in the sju.edu math bingo page of Sean and Sylvia Forman. He goes to this page. After entering his e-mail address and creating a simple account, he is presented with a set of possible questions and answers. He selects the type of question that he wants the students to review. He checks all of the questions to make certain that they are appropriate for his students and what they have covered. He decided to delete two questions with trig integration that he had not covered in class. He enters the number of students and the number of questions to choose from. Then he prints out both the cards for the students and the list of problems to call. Since he likes this set of cards, we'll allow him to save it on the site for a later date. Scenario 3: Fylvia Sorman, Math Bingo Site administrator The administrator is getting ready to add integrals with partial fractions into the math bingo system. She goes to the administration area and creates a new category of problems, "integration with partial fractions." She then begins by entering latex snips to represent the questions (the integrals, which is what the instructor calls) and then the answers which appear on the bingo cards. She enters the snips one at a time. She can also define a default entry, so that the questions and answers always start out with the same values. This will save valuable time. She is able to move or copy previous questions around from one category to another. Once she enters the latex snips the program generates the corresponding html and stores them together. Images generated by latex2html will need to be stored in the database or they will be stored on the webserver somewhere and then indexed from the database. Perhaps just by how the code is written. This will be a bit dicey as each run of latex2html will want to overwrite the previous edition, so we'll have to generate the images and then rename the files with some unique text. Perhaps we'll need a db of the images, so that we can track what has been created thus far. Several of the questions are in a similar vein, so they may act as foils for one another. In this case the admin links them together and they appear in a foil table. Then when the teacher generates the cards, these problems will appear together on the cards. DB note: (we'll probably need these tables and columns in the tables) Question Table qID, uID, question, answer, html_code Category Table cID parentID cName available (Y,N) QuesCat Table qID cID CardSets sID uID rKey eMail Title CardQuestions sID qID Foils fID FoilsQues fID qID Users uID email name school ---------------------------------------------------------------------- Non-goals ---------------------------------------------------------------------- The program will not compute the answer of the input integrals and it will not provide a gui interface for those unfamiliar with latex. At the moment, we will not allow the user to enter their own questions. This would be something for v2.0. One main problem for this would be that we would need to double-check all of the instructors questions ahead of time. This might be solvable using AIM. In fact, using AIM may allow us to enter the questions more easily. Studying AIM should be an early task. ---------------------------------------------------------------------- Flowchart ---------------------------------------------------------------------- User arrives to our home page Select types of problems to produce Select parameters for bingo cards -- Use our library -- How many cards -- Save setup -- Output format Use our library, show potential functions and ask them to exclude any not appropriate. (Question and answer are side-by-side) Get a printout of the cards (postscript, pdf, or latex, maybe html) Save this setup for future use. (gather e-mail and send them a number). We will also e-mail them with a link they can save that will allow them to return to their cards. ---------------------------------------------------------------------- Screen-by-screen User areas ---------------------------------------------------------------------- Home page ---------------------------------------------------------------------- Describes the service and lists the types of problems that are in our DB. Clearly credits sju and authors. Provides means for feedback and questions. Contains an FAQ. Bingo card parameters ---------------------------------------------------------------------- Use our functions or enter their own - Select from our possible functions. The number of problems the cards should be built from. The number of cards to create. The layout of the cards. The output format for the cards Free center square or not. Create multiple call sequences with different winners and non-repeated entries. This page should be dynamic as it requires us to know how many functions we have currently available for card selection. Some study on how many steps it will take to win given a certain number of inputs could be considered. For example, a set of cards of 24 non-free entries selected from a pool of 200 functions may not yield a bingo for some time. However, if this is given to 1000 students this may be the best way to go. For example, we could tell faculty, that with fifty questions and ten cards you will likely need twelve (or whatever the correct value is) steps to get a bingo. -------------------------------------------------------------------- Users enter their own functions (for a later date) ---------------------------------------------------------------------- This is an advanced feature and may not be made available until later on. This might also be a way that we could support different textbooks as we could require all of the functions used can become available to others and we could allow people to create new sets of cards for different topics. Combinatorics, arithmetic, languages, etc. An educational bingo revolution. This would require us to use latex2html to allow latex entry of the functions. We would then want to show the result to the designers, so that they could edit anything that they didn't want or didn't turn out appropriately. Some sort of gui for drawing things might be appropriate as well. There may need to be some sort of way to store images on the site in case someone would want to use pictures. Using an existing library ---------------------------------------------------------------------- In this case, the problems within the library are listed and the user can include or exclude problems as they see fit. The problems will likely be divvied up in some sort of category system. We may want to support something like. Integrals -> trig Integrals -> substitution .... Derivatives -> product rule They could select multiple libraries and select some random number of problems from each library or list them all and then select the ones they want. Tech note: the libraries of problems would be stored in the DB as latex text and then the entries would be regenerated as needed with latex2html through an administration area. Receiving the resulting cards ---------------------------------------------------------------------- After the selection, the cards are generated and stored into a DB as a new set. This set is then output in a variety of formats and stored temporarily. PDF format may require some work or may just require dvi2pdf if we can use latex to generate everything. I'm not sure how we would generate the html format because the page issue would be a problem. I would have to see if there is a way to force page breaks within an html document. Having to go through each page and then hit print would be very annoying. We could also produce just latex or ps outputs as well. This will also be accessible from a url call that will recall earlier created bingo card sets. Generating the calling key ---------------------------------------------------------------------- The instructor's key would list all of the various entries on the cards and then provide a calling order for the card entries. It may be possible to state when each card would get a bingo. You could also print out alternate calling orders that don't re-use previous entries and have different winners. This way you can get different winners on the same sets cards. That would be an interesting bit of code to calculate who will win and when. Also, we will want an output where all of the cards are printed out in a single or a small number of pages. Saving the current card layout. ---------------------------------------------------------------------- The set of cards and keys that the instructor constructs will be saved based on a random key and this will be stored along with their e-mail address. This information will be e-mailed to them as a url that they will be able to click on to then re-use at a later date. ---------------------------------------------------------------------- General Stages (or versions) ---------------------------------------------------------------------- 1) Allow us to enter questions 2) Allow users to enter questions and their answers. 3) Allow users to enter questions and then we generate the answers using AIM (maple, mathematica, etc.) ---------------------------------------------------------------------- Screen-by-Screen Admin Area ---------------------------------------------------------------------- -Command center (password protected using .htaccess) displays the number of questions, categories, users, cards stored provides links to the various tasks that the admin will need to do. Add a new category Edit a category Move categories below other categories Write a new question and answer Edit a QandA View the html for a QandA Add a QandA to a category Delete a QandA from a category Add a user Delete a user View a user Create, delete, edit a foil set add a question to a foil set These will all be very basic pages, no design if any. ---------------------------------------------------------------------- Open Issues ---------------------------------------------------------------------- Can we create PDF files? Can we hook this in with latex easily? Do we need to write a latex snippet evaluator? Could this eventually be tied in with maple or mathematica and would those people eventually want to buy such a program? Could we charge memberships to textbooks to enter their problems into this system?