Recipes
Warning: Wiki should not be edited directly. Edit the files in the ./wiki/ folder instead and make a PR.
Once we have successfully sorted and placed the required information into chunks, we can now use recipes to transform the acquired knowledge into a usable format. From there, we only need to print out the documents and then we can have informative artifacts. A recipe is similar to the process of unboxing every chunk, taking out the necessary information, and laying it out nicely on a tray for easy use and reuse. If we want to change an aspect of the generated document, we merely modify the recipe in a manner to create that change. This way, information that remains in the chunks may be kept when transitioning between different kinds of documents. Essentially, we start from a foundation of knowledge and build a complete artifact by calling the proper recipe for that document. This allows Drasil to keep a certain magnitude of modularity along with all the encoded information from chunks.
Recipes are often just procedures, or a set of instructions that will produce a desired result given appropriate inputs. In a way, this style of generation embraces the spirit of functional programming. In Drasil specifically, we always start off with some information input. The information may come from different places (eg. drasil-data, drasil-metadata, a user's examples), but it is always given to Drasil through chunks. From there, the Drasil recipes (and specifically the SRS recipes found in drasil-docLang) organize all the information into something usable. Once all the information is organized the way we want it, we can send it off to the Drasil generators/printers and get our up-to-date generated artifacts. Of course, all of this work is not quite as simple as the diagram shown below, but its a good start to thinking about the process of generators in a functional manner.
Currently, the most-used recipe in Drasil is one to generate Software Requirements Specification (SRS), which can be found in the drasil-docLang package. It has gone through many iterations of refinement and rationalization, and we have arrived at a point where creating a new physics-based example only requires inputting the necessary knowledge and organizing functions created in the document language. This recipe takes in all of its input from SystemInformation and PrintingInformation which are given to the gen function. And that function formats the information and prepares it for the printers, which then gives us the formatted SRS documents in the manner we desire.
The document structure of a full SRS can be separated into different sections as follows:
- Reference Material
- Table of Units
- Table of Symbols
- Table of Abbreviations and Acronyms
- Introduction
- Purpose of Document
- Scope of Requirements
- Characteristics of Intended Reader
- Organization of Document
- Stakeholders
- The Client
- The Customer
- General System Description
- System Context
- User Characteristics
- System Constraints
- Specific System Description
- Problem Description
- Termonology and definitions
- Physical System Description
- Goal Statements
- Solution Characteristics Specification
- Assumptions
- Theoretical Models
- General Definitions
- Data Definitions
- Instance Models
- Data Constraints
- Properties of a Correct Solution
- Problem Description
- Requirements
- Functional Requirements
- Non-Functional Requirements
- Likely Changes
- Unlikely Changes
- Traceability Matrices and Graphs
- Values of Auxiliary Constants
- References
- Appendix
Each section is generated by a recipe found in the document language and the SystemInformation gathered from each example. This way, a user will not have to worry about where the inputted information will be going. Their focus can be dedicated to giving Drasil the information and calling the recipe to create the document for them, rather than organizing the location and display of every bit of information themselves.