This template structure is an AsciiDoctor implementation of the four "books" described by Bertrand Meyer in his book Handbook of Requirements and Business Analysis.
A copy of the chapter describing how the structure should be filled from a bird-eye point of view is available in Chapter 3. for more information, please refer to (1) the book or (2) your lectures on requirements engineering & project management.
The template is provided in a way that fits McMaster University course portfolio (Faculty of Engineering, CAS department). It is explicitely designed as a support for CS/SE 3RA3.
A makefile is provided to automate the compilation of the requirements document. To check if your installation is correct, use the make check_env command:
mosser@azrael tpl % make check_env
/opt/homebrew/bin/asciidoctor
/opt/homebrew/bin/asciidoctor-pdf
/opt/homebrew/bin/plantuml
/opt/homebrew/bin/dot
Dot version: dot - graphviz version 8.1.0 (20230707.0739)
Installation seems OK. File generation OKmetadata.adoc)The metadata.adoc file contains all the metadata for your document:
Name <email>), separated by semicolons. The template supports up to six authors.:project-title: is the name of your project. You can refer to it in your text by using {project-title}.:course-number: refers to the course code associated to this delivery (e.g., 3RA3, 4G06):course-term: refers to the term associated to this course (e.g., Fall 2023):rev-number: is the REV ision NUMBER of the document (should start at 1):env-draft: is a boolean variable to include the hints about the content of each section in the section. Comment this line (// :env-draft:) to remove the hints in your final deliveryparts directory. Each book is in its own subdirectory.
parts/goals/G3.adoc.puml in the models directory, the makefile will compile it into a vectorial format (SVG) so that you can include it in your document.
models/domain_model.puml and models/use_cases.puml, included in sections XX and YY (respectively)!include ../_style/puml.style) to use McMaster colour palette. If not, you'll use the default PlantUML theme.adoc files in the appendix directory, and to include them in your index.adoc file
[appendix] annotation so that Asciidoctor knows you're declaring an appendix section. Look how Appendix A is defined in appendix/A_example.adoc and included in index.adoc.To create the PDF document, simply run make pdf (this is the default target). It'll create a file named index.pdf with the compiled version of your document.
mosser@azrael tpl % make pdf
asciidoctor-pdf --theme _style/mcmaster.yml index.adoc If you want to create an HTML version of your document, run make html. It'll create an index.html file containing your document
mosser@azrael tpl % make html
asciidoctor index.adoc Writing requirements is an incremental and iterative process. As such, you should not write your document from A to Z in one shot, but instead think of multiple intermediate milestones.
Based on the experience accumulated by Dr. Paige & Dr. Mosser on teaching CS/SE 3RA3, we recomend the following milestones:
_style/logo.png file is McMaster CAS department official logo_style/license.png file is automatically included at the bottom of each pageThe file _style/mcmaster.yml extends the default PDF exportation style to match McMaster color palette and logos.
The stylesheet is defined in the file named _style/puml.style. It refers to classical UML elements used in requirements document, using McMaster marroon and gold color palette.
PlantUML documentation is now really helpful to define theme, so it was defined in a "monkey see, monkey do" way based on examples available in PlantMUL source code repository: https://github.com/plantuml/plantuml/blob/master/themes/