Writing a complete system specification is vital to a properly managed project. SpecWriter is designed to help you easily create robust system specifications for user requirements documentation and in-house use. Using this tool, you can enter all the relevant information for a file that you need to create as part of a larger system, and print out an attractive report on that file to include with a bid or to pass off to the programmers for file creation reference and reference at project's end to see how the finished product stacks up against your initial design. In addition to just entering field names, types, etc., SpecWriter provides a framework for you to annotate this information, providing an added level of depth to your spec. SpecWriter can also generate text lists of the information that you enter which can be cut and pasted into documents in other applications. SpecWriter is intuitive enough that you can just use it and figure it out, but here's the full documentation for reference's sake. SpecWriter was built on the same framework as SystemText, so if you understand that tool, you're 90% of the way to understanding this one.
General Layout Notes
SpecWriter breaks down a file's information into 6 types, each with its own layout. These layouts are: File Info, Fields, Relationships, Layouts, Scripts and Value Lists. They are accessible by clicking on the green buttons at the top of each layout, one for each type of data. All data can be entered directly into the portals. You can create a new portal row by clicking on the "New ____" button. Additionally, each type of data can be printed in its own report by clicking on the "Print _____" button on that particular layout. SpecWriter can also compile all the information for a data type into a return-seperated list of text by clicking on the "Generate Text" button on that layout.
On each layout, with the exception of File Info, the data is listed in portals. As in most tools in LitheFM, these portals can be sorted by clicking on the column headers. This will cause the data in the portal to sort, and the portal will display a graphical highlight showing which column is the sort criteria. Clicking on the "*" header will return the portal to its original order.
Each row in a portal displays a small icon which resembles a sticky note. Clicking on this icon will allow you to enter notes for that item in the large field on the right hand side of the layout. In the case of fields, layouts and value lists, this will also display some other information for the item - field calculations, fields on the layout and value list items respectively - in the large field in the lower right corner of the layout. The SpecWriter reports are designed to accomodate up to a page of notes per item, we find that usually a few lines is sufficient. In addition to just viewing the notes, you can for fields and relationshiops hold the option key down while you click on the notes icon to build the item in question, see the notes on those specific layouts for more info.
There is a dark strip with text at the bottom of each layout. This text tells you who entered and last modified the current record and when, and gives you feedback on the found set.
General Layout Buttons
(Layout Buttons): The green buttons to navigate to each data type's layout are located at the top of each screen, clicking on a button will take you to that layout, and that button will highlight in grey.
(Arrow Buttons): At the right end of the layout buttons are two buttons labelled with arrows that allow you to scroll between records. As in all tools in LitheFM, holding the option key while you click on these buttons will take you to the first or last record in the found set rather than the previous or next records in the found set.
"Clear (___)": Each layout has some version of this button labelled with that datatype (e.g. "Clear Fields"). Clicking on this button will delete the current entries (including notes). Holding the option key down while you click this button will suppress the dialog confirming you intention if there is already data in the portal.
"Generate Text": Clicking on this button will generate a return seperated list of the data in the layout's portal. The text will be generated according to the current sort order of the portal. The text thus generated is also subject to the preferences set for reports on the file info layout (see "File Info" below for more information). Holding the option key down while you click this button will suppress the dialog confirming you intention if there is already data in the text field.
"Print (____)": This button prints a report for just the information on the current layout. The information in the report will be sorted the same as the current portal sort, and is subject to the preferences set for reports on the file info layout. Printing reports brings up the standard print dialog, at which time you can cancel the printing if you choose. You can bypass the print dialog by holding down the option key while you click this button.
"Hide": Just for convenience, this button hides the windows for the SpecWriter and SpecWriter Data files.
"Close": This button closes both the SpecWriter and SpecWriter Data files, but does not quit the Filemaker application.
Special Entry Options
When you click on the notes icon, you can enter notes in the field at right for the selected item. Fields, Relationships, Layouts and Value Lists, a field is also provided to enter field options, relationship options, fields on the layout and value list items respectively. However, you still have to type this data in a bulk fashion.
To make the process of entering fields and relationships more detailed and expedient, we have included an option to "Build" these records using a familiar interface. If you hold down the option key while you click on the notes icon for a relationship, a small window will pop-up where you can specify a name for the relationship and pick a file from any existing records in SpecWriter. You can then specify the match fields using value lists which contain all the fields entered for the current file and the file you specified as the related file. Click continue to save this as the current relationship definition, cancel to cancel your work. Note that continuing will overwrite any existing relationship option information.
If you hold down the option key while you click on the notes icon for a field, a small window will appear where you can enter the options for the field. This window will vary based on the type of field you are entering, but contains all the options you would expect for that type. Click continue to save this as the current field options, cancel to cancel your work. Note that continuing will overwrite any existing field option information.
Existing field options and relationship definitions will not be parsed out into these "Specify" windows, but they do allow you to build options quite quickly. If you need to alter just a portion of the relationship or field options, you make that change in the field on the main layout.
File Info Layout
The file info layout is where most of the functionality lies in SpecWriter. This is where you build and delete records, perform finds, set preferences and do record-wide updates and printing. The basic file info consists of the following fields:
"File Name" - What you wish to call the new file.
"System Name" - Enter the name of the larger system of which this file is part. Helps with finds.
"Location" - Where will this file be stored?
"Multi-User" - The file sharing status of the file.
"File Description" - A field where you can enter a general description of the file, can be included on the printouts.
Summary Fields - These fields tell you how many of each type of data are associated with this file.
This layout also has a portal where you can enter groups, passwords and access notes, enter these directly into the portal fields. This information is printed as part of the file info and full SpecWriter reports. Like all portals in the Toolkit, this one can be sorted by clicking on the column headers. Doing so will cause the portal to sort and a graphical highlight to display showing the sort criteria.
Finally, this layout provides space where you can set the preferences for report printouts and text generation formating. See the sections below for more on these options.
File Info Buttons:
"Print File Info": This will print a report for just the file info, subject to the preference to print the file description.
"Clear Access": Clicking on this button will delete all access privilage information which has been entered. Holding down the option key while you click this button will suppress the dialog prompting you to confirm you intention.
"New Record": Click on this button to begin the process of entering a new file. This will create a new record and put the cursor in the "File Name" field. This is the only way you should enter new records, as it properly enters and updates all unique identifiers.
"Duplicate Record": This button will duplicate the current file record, including all of its associated items (fields, relationships, notes, etc). This can be very useful for files that are similar to one another, or you can build a template record and keep duplicating it for each new file that you need.
"Find": Use this button to perform a find based on any criteria you enter on the File Info layout. If multiple matching records are found, SpecWriter will display a list screen showing the records sorted by file name. Click on a row to return to the file info layout for that record. Notice that when you click on this button, the caption changes to "Browse" if you wish to cancel the find, simply click on this button again to return to Browse mode.
"Import": SpecWriter lets you import records from our SystemText tool, including all associated items and notes. This can be very useful when you need to make a spec for a new file that closely resembles something you have done before. Note that SpecWriter will import the entire found set from SystemText, so verify that the found set is correct before performing this function.
"Delete Record": Clicking on this button will delete the curent record. As in all tools in the LitheFM Toolkit, hold down the option key while clicking this button to suppress the dialog verifying your intention.
"Print Full Report": Use this button to print a complete report for all the data types for the current file record. This is really just like going to each layout and clicking on the "Print ___" button. Each data type begins on its own page. All portal sorts and report preferences apply. You can suppress the print dialogs by holding down the option key for the duration of this process.
"Hide": Just for convenience, this button hides the windows for the SpecWriter and SpecWriter Data files.
"Close": This button closes both the SpecWriter and SpecWriter Data files, but does not quit the Filemaker application.
Report and Text Generation Preferences
There are a number of preferences you can set on the file info layout. Check the box next to each preference you would like to be enabled. All of these preferences are global and therefore apply to all records, so be sure to check your preferences before you begin printing.
"Include File Description": If this preference is enabled the file description will be included on the file info report. The report is structured to allow for a file description of approximately a page.
"Include Field Notes": If this preference is enabled, the any notes you have entered about a particular field will be included on the printout or in the text that is generated on the fields layout.
"Include Relationship Notes": If this preference is enabled, the any notes you have entered about a particular relationship will be included on the printout or in the text that is generated on the relationship layout.
"Include Layout Notes": If this preference is enabled, the any notes you have entered about a particular layout will be included on the printout or in the text that is generated on the layout layout.
"Include Script Notes": If this preference is enabled, the any notes you have entered about a particular script will be included on the printout or in the text that is generated on the script layout.
"Include Value List Notes": If this preference is enabled, the any notes you have entered about a particular value list will be included on the printout or in the text that is generated on the value list layout.
"Format Item Name": This preference applies only to text generation. You can use this option to format the text that is generated by specifying the characters you would like to see on either side of the item name. For instance, if you wanted a blank line between each field in the text, and you wanted to put the field name on its own line above the field type, you could check this option and enter a return in each of the boxes that surround "name". Or, if you wanted to preface each relationship name with "##" you would enable this option and just enter those characters - without the quotes - in the box before "name". Play with it, you'll get the hang of it.
"Preface Notes With": Much like the above option, but applies to the notes for any given data type. Enter any characters here (including a carriage return) that you would like to appear before an item's note in the text generated.
