marko 0.1.0 → 0.3.0

data/lib/assets/samples/business-case.md

@@ -0,0 +1,116 @@
+# Business Case
+
+@@skip
+
+The purpose is communication! Each section should be written in the parlance of the intended audience; it should only contain enough information to help decision making.
+
+## Executive Summary
+
+@@todo It should succinctly convey vital information about the project and communicate the entire story to the reader.
+
+## Finance
+
+@@todo for those who will be approving funding and should include
+
+@@skip
+
+__A financial appraisal__ - identify the project's financial implications, compare project costs to forecast benefits, ensure every cost is considered, assess value of money, and predict cash flow.
+
+__A sensitivity analysis__ - assess project risks, measure the impact of project outcomes or assumptions, and lets project accountants experiment with possible scenarios.
+
+## Project Definition
+
+@@skip
+
+This is the largest part of the business case and is for the project sponsor, stakeholders, and project team. It should address the following...
+
+### Business Objective
+
+@@todo What is your goal?
+@@todo What is needed to overcome the problem?
+@@todo How will the project support the business strategy?
+
+### Benefits and Limitations
+
+@@todo explain why you need a project in financial and non-financial benefits in turn
+
+@@skip
+
+* Generate revenue
+* Save costs through efficiencies
+* Improve quality
+* Improve customer service
+* Remain competitive
+* To align to corporate strategy
+
+### Option Identification and Selection
+
+@@todo identify the potential solutions to the problem and describe them in enough detail for the reader to understand.
+
+@@skip
+
+For instance, if the business case and proposed solution makes use of technology, make sure to explain how the technology is used and define the terms used in a glossary.
+
+The final business case may contain three to five options - the short list - that includes a do nothing or benchmark option.
+
+### Scope, Impact, and interdependencies
+
+@@todo describes the work needed to deliver the business objective and identifies those business functions affected by the project
+
+@@todo state the project's scope and boundaries
+
+@@todo consider the failure of other interrelated projects and how such dependencies may impact benefits
+
+### Outline Plan
+
+@@todo list the major deliverables and include a brief project plan
+
+@@skip
+
+Ideally, the project should be divided into stages with key decisions preceding each stage. Use this section to answer the following questions:
+
+* What is required?
+* How is id done?
+* Who does what?
+* When will things happen?
+
+### Market Assessment
+
+@@skip
+
+Provide a thorough assessment of the business context and make the underlying business interests explicit. Show a complete understanding of the marketplace in which your business operates, considering political, economical, sociological, technological, legal, and environmental factors (or PESTLE, if you like)
+
+### Risk assessment
+
+@@skip
+
+Summarize the significant risks and opportunities and how they are managed. The risks included should cover those that could arise from you projects or the organization's ability to deliver change, including the following questions:
+
+* What risks are involved?
+* What are the consequences of a risk happening?
+* What opportunities may emerge?
+* What plans are in place to deal with the risks?
+
+### Project Approach
+
+@@skip
+
+The project approach describes how the project is tackled. That is, the way in which work is done do deliver the project. For instance, a project with much of the work contracted out is likely to take a different approach to a project that develops an in-house solution.
+
+### Purchasing Strategy
+
+@@skip
+
+This section describes how a project is to be financed and whether a decision to buy, lease, or outsource should be taken by the organization before purchasing.
+
+Moreover, the purchasing strategy should describe the purchasing process used. A formal procurement process may save time and money and reduce project risk.
+
+## Project Organization
+
+@@skip
+
+The section is of most interest to the project manager, project team, and managers responsible for delivering work to the project, and should include:
+
+1. __Project governance__ - show how the project is structured and the different levels of decision-making.
+
+2. __Progress reporting__ - define for project progress will be recorded and reported to the project board.

data/lib/assets/samples/ears.md

@@ -0,0 +1,112 @@
+% Easy approach to requirements syntax (EARS)
+
+# Overview
+
+Type              Template
+----------------- --------
+Normal behavior   The `system name` shall `system response`.
+Unwanted behavior If `optional preconditions trigger`, then the `system name` shall `system response`.
+Event-driven      When `trigger` the `system name` shall `system response`.
+State-driven      While `in a specific state` the `system name` shall `system response`.
+Options           Where `feature is included` the `system name` shall `system response`.
+Complex           Where the car includes an "owner alert"  system, if the car detects attempted intrusion, then the car shall send a message to the owner and activate the car alarm.
+
+# General template
+
+`optional preconditions` `optional trigger` the `system name` shall `system response`.
+
+# Normal behaviour
+
+The `system name` shall `system response`.
+
+## Car
+
+__[car.1]__ The car shall have a maximum retail sale price of XXX.
+
+__[car.2]__ The car shall be compliant with the safety requirements defined in XXX.
+
+## Laptop
+
+__[lap.1]__ The laptop shall have a mass of no more than XXX grams.
+
+__[lap.2]__ The laptop shall have a minimum battery life of XXX hours.
+
+# Unwanted behavior
+
+If `optional preconditions` `trigger`, then the `system name` shall `system response`.
+
+## Car
+
+__[car.1]__ If the car detects attempted intrusion, then the car shall operate the car alarm.
+
+__[car.2]__ If the car detects low oil pressure, then the car shall display a "low oil pressure" warning.
+
+## Laptop
+
+__[lap.1]__ If the incorrect password is entered, then the laptop shall display XXX warning message.
+
+__[lap.2]__ If the laptop is connected to a non-compatible device, then the laptop shall prevent transfer of data, prevent transfer of charge, display XXX warning message and not be damaged.
+
+# Event-driven, When
+
+When `trigger` the `system name` shall `system response`.
+
+## Car
+
+__[car.1]__ When the clutch pedal is depressed, the car shall disengage the driving force.
+
+__[car.2]__ When the "turn indicator" command is received, the car shall operate the indicator lights on the front, side and rear of the vehicle, and provide audible and visual confirmation to the driver.
+
+## Laptop
+
+__[lap.1]__ When the laptop is off and the power button is pressed, the laptop shall boot up.
+
+__[lap.2]__ When the laptop is running and the laptop is closed, the laptop shall enter "powersave" mode.
+
+# State-driven, While
+
+While `in a specific state` the `system name` shall `system response`.
+
+## Car
+
+__[car.1]__ While the ignition is on, the car shall display the fuel level and the oil level to the driver.
+
+__[car.2]__ While the key is in the ignition, the car alarm shall be inhibited.
+
+__[car.3]__ While the handbrake is applied, the wheels shall be locked.
+
+## Laptop
+
+__[lap.1]__ While the laptop is running on the battery and the battery is below XXX % charge, the laptop shall display "low battery".
+
+__[lap.2]__ While an external audio output device is connected, the laptop shall mute the built-in speaker and send the audio output signal to the external audio output device.
+
+# Option, Where
+
+Where `feature is included` the `system name` shall `system response`
+
+## Car
+
+__[car.1]__ Where the car has electric windows, the electric window controls shall be on the driver's door panel.
+
+__[car.2]__ Where the car includes automatic windscreen wipers, the car shall sense moisture on the windscreen and operate the windscreen wipers without driver commands.
+
+## Laptop
+
+__[lap.1]__ Where a "long life" battery is fitted, the laptop shall have a minimum battery life of XXX hours.
+
+__[lap.2]__ Where the laptop is a "lightweight" model, the laptop shall have a mass of no more than XXX grams.
+
+# Complex requirements
+
+## Car
+
+__[car.1]__ Where the car includes an "owner alert"  system, if the car detects attempted intrusion, then the car shall send a message to the owner and activate the car alarm.
+
+__[car.2]__ While the car is being driven forwards above a speed of XXX, if the driver attempts to engage reverse gear, then the car shall prevent engagement of reverse gear.
+
+## Laptop
+
+__[lap.1]__ Where the laptop includes "voice input" option, while the voice input option is selected, the laptop shall accept voice input commands.
+
+__[lap.2]__ While the laptop is running on mains electrical power, if the power cable is disconnected, then the laptop shall display a warning message.

data/lib/assets/samples/gen_punch_domain.rb

@@ -0,0 +1,183 @@
+# Generate actors, use cases, and entites from Punch::Domain::DSL
+# see [Punch](https://github/nvoynov/punch)
+# 
+require "optparse"
+require "erb"
+require "punch"
+require "optparse"
+require_relative "domain"
+require_relative "sampler"
+include Punch
+
+@domain = build_domain
+
+parser = OptionParser.new {|cmd|
+  cmd.banner = "Usage: ruby marko.rb [OPTIONS]"
+  cmd.on('-b DIRECTORY', '--basedir DIRECTORY',
+    'Setup base punching directory', String)
+  cmd.on('-d', '--dry-run true|false', 'Print result instead of punch', TrueClass)
+}
+
+puts "Punch Marko Genearator v0.1"
+puts "#{parser}"
+options = {}
+parser.parse(ARGV, into: options)
+
+nulldir = File.expand_path(__FILE__).sub(/\.rb$/, '')
+basedir = options.fetch(:basedir, nulldir)
+dryrun  = options.fetch('dry-run'.to_sym, true)
+
+generate = proc{|file, body|
+  meth = dryrun == true ? Sampler.method(:preview) : Sampler.method(:write)
+  meth.(file, body)
+}
+
+samples = Sampler.()
+# special case for services, few files
+services_source = "fr/uc/%{uc}.md"
+services_sample = samples.delete(services_source)
+samples.each{|source, sample|
+  location = File.join(basedir, source)
+  erbsample = sample.match?(/@domain/)
+  content = if erbsample
+    renderer = ERB.new(sample, trim_mode: "-")
+    renderer.result
+  else
+    sample
+  end
+  generate.(location, content)
+}
+
+# services_source = "fr/uc/%{uc}.md"
+# services_sample = samples.delete(service_source)
+renderer = ERB.new(services_sample, trim_mode: "-")
+@domain.services.each{|model|
+  modelstr = model.name.to_s.gsub(/(\s|_)/, '.')
+  location = File.join(basedir, services_source % {uc: modelstr})
+  @model = model
+  generate.(location, renderer.result)
+}
+
+
+__END__
+
+@@sample actors.md
+# Actors
+{{id: actors, parent: root}}
+
+The system should provide services for the following actors:
+
+@@list
+
+<% @domain.actors.each do |actor| -%>
+## <%= actor.name.capitalize %>
+{{id: .<%= actor.name.downcase %>}}
+
+<%= actor.desc %>
+<% end %>
+
+@@sample fr/uc.md
+# Use Cases
+{{id: fr.uc, parent: fr}}
+
+@@list
+
+<% @domain.actors.each do |actor| -%>
+<%
+  order_index = actor.services
+    .map(&:name)
+    .map(&:to_s)
+    .map{ _1.gsub(/(\s|_)/, '.') }
+    .map{ _1.split(?.).drop(1).join(?.) }
+    .join(' .')
+-%>
+## <%= actor.name.capitalize %>
+{{id: fr.uc.<%= actor.name %>, order_index: .<%= order_index %>}}
+
+The system must provide the following services for <%= actor.name.capitalize %> actor:
+
+@@list
+
+<% end %>
+
+@@sample fr/en.md
+
+# Entities
+{{id: .en, parent: fr}}
+
+The system utilises the following entities:
+
+@@list
+
+<% @domain.entities.each do |model| -%>
+## <%= model.name.capitalize %>
+{{id: .<%= model.name.downcase %>}}
+
+<%= model.desc %>
+
+The entity should provide the following properties:
+
+Property | Type | Multiplicity | Description
+-------- | ---- | ------------ | -----------
+<% model.params.each do |param| -%>
+<%= param.name %> | <%= param.sentry %> | 1 | <%= param.desc %>
+<% end -%>
+
+Table: Entity "<%= model.name.capitalize %>"
+
+<% end %>
+
+@@sample fr/uc/%{uc}.md
+<%
+  dummy = @model.name.to_s.gsub(/(\s|_)/, '.').split(?.).map(&:downcase)
+  id = dummy.drop(1).join(?.)
+  parent = dummy.first
+  header = dummy.drop(1).map(&:capitalize).join(?\s)
+-%>
+# <%= header %>
+{{id: .<%= id %>, parent: fr.uc.<%= parent %>}}
+
+<%= @model.desc %>
+
+**Actors and their Goals**
+
+1. User, wants to get
+2. System, wants to ensure
+
+**Guarantee**
+
+[Success]{.underline}
+
+1.
+2.
+
+[Failure]{.underline}
+
+1.
+2.
+
+**Extend**
+
+- no use case extensions
+@@todo - [\[fr.uc]]
+
+**Include**
+
+- no use case inlcusions
+@@todo - [\[fr.uc]]
+
+**Main flow**
+
+1.
+2.
+
+**Extension**
+
+[1a] something faulty
+
+**Data**
+
+Entities:
+
+@@todo - [\[fr.ent.]];
+@@todo - [\[fr.ent.]].

data/lib/assets/samples/requirements.md

@@ -0,0 +1,105 @@
+% Requirements (BABOK)
+
+# Classification
+
+__Business requirements__: statements of goals, objectives, and outcomes that describe why a change has been initiated. They can apply to the whole of an enterprise, a business area, or a specific initiative.
+
+__Stakeholder requirements__: describe the needs of stakeholders that must be met in order to achieve the business requirements. They may serve as a bridge between business and solution requirements
+
+__Solution requirements__ : describe the capabilities and qualities of a solution that meets the stakeholder requirements. They provide the appropriate level of detail to allow for the development and implementation of the solution. Solution requirements can be divided into two sub-categories:
+
+* __Functional requirements__: describe the capabilities that a solution must have in terms of the behaviour and information that the solution will manage, and
+* __Non-functional requirements or quality of service requirements__: do not relate directly to the behaviour of functionality of the solution, but rather describe conditions under which a solution must remain effective or qualities that a solution must have.
+
+__Transition requirements__: describe the capabilities that the solution must have and the conditions the solution must meet to facilitate transition from the current state to the future state, but which are not needed once the change is complete. They are differentiated from other requirements types because they are of a temporary nature. Transition requirements address topics such as data conversion, training, and business continuity.
+
+# Life cycle
+
+The purpose is to ensure that business, stakeholder, and solution requirements and designs are aligned to one another and that the solution implements them.
+
+@@list
+
+## Trace  
+
+Business Needs <-> Business Requirements <-> Stakeholder Requirements <-> Solution Requirements (Design <-> Code <-> Test)
+
+## Maintain
+
+The purpose is to retain requirement accuracy and consistency throughout and beyond the change during the entire requirements life cycle, and to support reuse of requirements in other solutions.
+
+## Prioritize
+
+Typical factors that influence prioritization include:
+
+__Benefit__ the advantage that accrues to stakeholders as a result of requirement implementation, as measured against the goals and objectives for the change. The benefit provided can refer to a specific functionality, desired quality, or strategic goal or business objective. If there are multiple stakeholders, each group may perceive benefits differently. Conflict resolution and negotiation may be employed to come to consensus on overall benefit.
+
+__Penalty__ the consequences that result from not implementing a given requirement. This includes prioritizing requirements in order to meet regulatory or policy demands imposed on the organization, which may take precedence over other stakeholder interests. Penalty may also refer to the negative consequence of not implementing a requirement that improves the experience of a customer.
+
+__Cost__ the effort and resources needed to implement the requirement. Information about cost typically comes from the implementation team or the vendor. Customers may change the priority of a requirement after learning the cost. Cost is often used in conjunction with other criteria, such as cost-benefit analysis.
+
+__Risk__ the chance that the requirement cannot deliver the potential value, or cannot be met at all. This may include many factors such as the difficulty of implementing a requirement, or the chance that stakeholders will not accept a solution component. If there is a risk that the solution is not technically feasible, the requirement that is most difficult to implement may be prioritized to the top of the list in order to minimize the resources that are spent before learning that a proposed solution cannot be delivered. A proof of concept may be developed to establish that high risk options are possible.
+
+__Dependencies__ relationships between requirements where one requirement cannot be fulfilled unless the other requirement is fulfilled. In some situations, it may be possible to achieve efficiencies by implementing related requirements at the same time. Dependencies may also be external to the initiative, including but not limited to other teams’ decisions, funding commitments, and resource availability. Dependencies are identified as part of the task Trace Requirements (p. 79).
+
+__Time Sensitivity__ the 'best before' date of the requirement, after which the implementation of the requirement loses significant value. This includes time-to-market scenarios, in which the benefit derived will be exponentially greater if the functionality is delivered ahead of the competition. It can also refer to seasonal functionality that only has value at a specific time of year.
+
+__Stability__ the likelihood that the requirement will change, either because it requires further analysis or because stakeholders have not reached a consensus about it. If a requirement is not stable, it may have a lower priority in order to minimize unanticipated rework and wasted effort.
+
+__Regulatory or Policy Compliance__ requirements that must be implemented in order to meet regulatory or policy demands imposed on the organization, which may take precedence over other stakeholder interests.
+
+## Assess changes
+
+The purpose is to evaluate the implications of proposed changes to requirements and designs. The task is performed as new needs or possible solutions are identified.
+
+* is it align to the change strategy and/or solution scope?
+* will increase the value of the solution?
+* has conflicts with other requirements?
+* or increase the level of risk?
+* can be traced back to a need?
+
+## Approve
+
+The purpose is to obtain agreement on and approval of requirements and designs for business analysis work to continue and/or solution construction to proceed.
+
+Business analysts are responsible for ensuring clear communication of requirements, designs, and other business analysis information to the key stakeholders responsible for approving that information.
+
+Approval of requirements and designs may be formal or informal. Predictive approaches typically perform approvals at the end of the phase or during planned change control meetings. Adaptive approaches typically approve requirements only when construction and implementation of a solution meeting the requirement can begin.
+
+Business analysts work with key stakeholders to gain consensus on new and changed requirements, communicate the outcome of discussions, and track and manage the approval.
+
+# Quality
+
+While quality is ultimately determined by the needs of the stakeholders who will use the requirements or the designs, acceptable quality requirements exhibit many of the following characteristics:
+
+Quality        Definition
+-------------- ----------
+Atomic         self-contained and capable of being understood independently of other requirements or designs.
+Complete       enough to guide further work and at the appropriate level of detail for work to continue. The level of completeness required differs based on perspective or methodology, as well as the point in the life cycle where the requirement is being examined or represented.
+Consistent     aligned with the identified needs of the stakeholders and not conflicting with other requirements.
+Concise        contains no extraneous and unnecessary content.
+Feasible       reasonable and possible within the agreed-upon risk, schedule, and budget, or considered feasible enough to investigate further through experiments or prototypes.
+Unambiguous the requirement must be clearly stated in such a way to make it clear whether a solution does or does not meet the associated need.
+Testable       able to verify that the requirement or design has been fulfilled. Acceptable levels of verifying fulfillment depend on the level of abstraction of the requirement or design.
+Prioritized    ranked, grouped, or negotiated in terms of importance and value against all other requirements.
+Understandable represented using common terminology of the audience.
+
+# Attributes
+
+Attribute                Definition
+------------------------ ----------------------
+rationale                a justification
+originator               who raised
+fit criterion            how to test if the solution matches the requirement
+customer satisfaction    if this requirement is successfully implemented; 1-5, uninterested - extremely pleased
+customer dissatisfaction measure of stakeholders unhappiness if this requirements is not part of the final product. 1-5, hardly matters - extremely displeased
+conflict
+complexity
+effort
+risk
+priority
+derived                  when a requirement is derived from another requirement
+depends                  when a requirement depends on another
+necessity                when it only makes sense to implement a particular requirement if a related requirement is also implemented.
+lower effort             when a requirement is easier to implement if a related requirement is also implemented.
+satisfy                  an implementation element, eg functional requirement satisfy a solution component
+validate                 a test case that can determine whether a solution fulfills the requirement