clerq 0.2.0 → 0.3.0

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

@@ -0,0 +1,135 @@
+# Business Case
+
+[source 1](http://whatis.techtarget.com/reference/How-to-write-a-business-case)
+
+[source 2](https://resources.workfront.com/project-management-blog/how-to-write-a-business-case-4-steps-to-a-perfect-business-case-template)
+
+## What is a business case?
+
+The business case is developed during the early stages of a project and outlines the __why, how, and who__ necessary to decide if the project is worth continuing. it's first developed during an initial investigation, has much more detail and should be reviewed by the project sponsor and key stakeholders before being accepted, rejected, canceled, deffered, or revised.
+
+BC gives your company the chance to access the following for each project:
+
+* Business problem or opportunity
+* Benefits
+* Risk
+* Costs including investment appraisal
+* Likely technical solutions
+* Timescale
+* Impact on operations
+* Organizational capability to deliver the project outcome.
+
+If a project is worth doing you need to answer 5 simple questions:
+
+* What is your goal?
+* What's stopping you from reaching the goal?
+* How much change is needed to overcome the problem?
+* Are you certain this will solve the problem?
+* Can you answer these questions quickly? Do you have evidence to support or refute your assumptions?
+
+# How to Write a Business Case
+
+The purpose is communication. Therefore, each section should be written in the parlance of the intended audience. Moreover, it should only contain enough information to help decision making.
+
+As you're writing, keep in mind:
+
+* The document should be brief and convey only the bare essentials
+* Make it interesting, clear and concise
+* Eliminate conjecture and minimize jargon
+* Describe your vision of the future
+* Demonstrate the value and benefits to project brings to the Business
+* Keep the number of authors to a minimum to ensure consistent style and readability.
+
+# Template
+
+The perfect BC for your project typically includes the following four section:
+
+## Executive Summary
+
+This short summary is the first section of the business case and the last written. It should succinctly convey vital information about the project and communicate the entire story to the reader.
+
+First impression are important. Get this right!
+
+## Finance
+
+This for those who will be approving funding and should include:
+
+1. __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.
+2. __A sensitivity analysis__ - assess project risks, measure the impact of project outcomes or assumptions, and lets project accountants experiment with possible scenarios.
+
+## Project Definition
+
+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
+
+* What is your goal?
+* What is needed to overcome the problem?
+* How will the project support the business strategy?
+
+### Benefits and Limitations
+
+This section describes the financial and non-financial benefits in turn. The purpose is to explain why you need a project. For instance, to:
+
+* Improve quality
+* Save costs through efficiencies
+* Reduce working capital - the difference between current assets and current liabilities
+* Generate revenue
+* Remain competitive
+* Improve customer service
+* To align to corporate strategy
+
+### Option Identification and Selection
+
+Identify the potential solutions to the problem and describe them in enough detail for the reader to understand.
+
+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
+
+This section describes the work needed to deliver the business objective and identifies those business functions affected by the project. it should also state the project's scope and boundaries. It describe what is included and what is excluded plus the key interdependencies with other projects.
+
+Consider the failure of other interrelated projects and show how such dependencies may impact benefits.
+
+### Outline Plan
+
+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?
+
+This outline plan should also list the major deliverables and include a brief project.
+
+### Market Assessment
+
+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
+
+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
+
+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
+
+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
+
+The last 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/knb/requirement-life-cycle.md

@@ -0,0 +1,47 @@
+% Some pieces from BABOK
+
+# Requirements 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.
+
+## 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.

data/lib/assets/knb/vision-document.md

@@ -0,0 +1,191 @@
+% Vision Document Template
+Company Name
+Vision Document for [Program Name]
+(r) 20XX [Company Name]
+
+# Revision History
+
+Date | Revision | Description | Author
+:--- | :------- | :---------- | :-----
+mm/dd/yy | 1.0 | Initial version | Author name
+
+# Table of Contents
+
+# 1 Introduction
+
+This section provides an overview of the Vision document.
+
+## 1.1 Purpose
+
+This document defines the strategic intent of the program. It defines high-level user needs, any applicable user personas, key stakeholders, and the general system capabilities needed by the users.
+
+## 1.2 Solution Overview
+
+State the general purpose of the product, system, application or service, and any version identification.
+
+* Identify the product or application to be created or enhanced.
+* Describe the application of the product, including its benefits, goals, and objectives.
+* Provide a general description of what the solution will and, where appropriate, will not do.
+
+## 1.3 References
+
+List other documents referenced, and specify the sources from which the references can be obtained. If a business case (Chapter 23) was developed to drive the program, refer to it or attach it.
+
+# 2 User Description
+To provide products and services that meet users’ needs, it is helpful to understand the challenges they confront when performing their jobs. This section should profile the intended users of the application and the key problems that limit the user’s productivity. This section should not be used to state specific requirements; just provide the background for why the features specified in Section 5 are needed.
+
+## 2.1 User/Market Demographics
+
+Summarize the key market demographics that motivate your solution decisions. Describe target-market segments. Estimate the market’s size and growth by the number of potential users or the amount of money your customers spend, trying to meet needs that your product/enhancement would fulfill. Review major industry trends and technologies. Refer to a market analysis, where available.
+
+## 2.2 User Personas
+
+Describe the primary and secondary user personas (see Chapter 7). A thorough analysis might cover the following topics for each persona:
+
+* Technical background and degree of sophistication  
+* Key responsibilities
+* Deliverables the user produces and for whom
+* Trends that make the user’s job easier or more difficult  
+* The user’s definition of success and how the user is rewarded
+* Problems that interfere with success
+
+## 2.3  User Environment
+
+Describe the working environment of the target user. Here are some suggestions.
+
+* How many people are involved in completing the task? Is this changing?
+* How long is a task cycle? How much time is spent in each activity? Is this changing?
+* Are there any unique environmental constraints: controlled environment, mobile, outdoors, and so on?
+* Which system platforms are in use today? Future platforms?
+* What other applications are in use? Does your application need to integrate with them?
+
+## 2.4 Key User Needs
+
+List the key problems or needs as perceived by the user. Clarify the following issues for each problem.
+
+* What are the reasons for this problem?
+* How is it solved now?
+* What solutions does the user envision?
+
+Ranking and cumulative-voting techniques for these needs indicate problems that must be solved versus issues the user would like to be solved.
+
+## 2.5 Alternatives and Competition
+
+Identify any alternatives available to the user. These can include buying a competitor’s product, building a homegrown solution, or simply maintaining the status quo. List any known competitive choices that exist. Include the major strengths and weaknesses of each competitor as perceived by the end user.
+
+### 2.5.1 Competitor 1
+
+### 2.5.2 Competitor 2
+
+# 3 Stakeholders
+
+Identify the program stakeholders, their needs, and their degree of involvement with the system. A table such as the following can be effective:
+
+Project<br/>Stakeholder | Degree of<br/> Involvement | Product Needs | Program Needs
+:---- | :---- | :---- | :----
+Stakeholder 1 | | |
+Stakeholder 2 | | |
+
+# 4 Product Overview
+
+This section provides a high-level view of the solution capabilities, interfaces to other applications, and systems configurations. This section usually consists of five subsections, as follows.
+
+## 4.1 Product Perspective
+
+This subsection should put the product in perspective to other related products and the user’s environment. If the product is independent and totally self-contained, state so. If the product is a component of a larger system, this subsection should relate how these systems interact and should identify the relevant interfaces among the systems. One easy way to display the major components of the larger system, interconnections, and external interfaces is via a system context block diagram.
+
+## 4.2 Product Position Statement
+
+Provide an overall statement summarizing, at the highest level, the unique position the product intends to fill in the marketplace. Moore [1991] calls this the product position statement and recommends the following format.
+
+For | (target customer)
+:-- | :----------------
+Who | (statement of the need or opportunity)
+The (product name) | is a (product category)
+That | (statement of key benefit, that is, compelling rea
+son to buy)
+Unlike | (primary competitive alternative)
+Our product | (statement of primary differentiation)
+
+A product position statement communicates the intent of the application and the importance of the program to all stakeholders.
+
+## 4.3 Summary of Capabilities
+
+Summarize the major benefits and features the product will provide. Organize the features so that the list is understandable to any stakeholder. A simple table listing the key benefits and their supporting features, as shown below, might suffice.
+
+Solution Features | Customer Benefit
+:---------------- | :---------------
+Feature 1         | Benefit 1
+Feature 2         | Benefit 2
+
+## 4.4 Assumptions and Dependencies
+
+List any assumptions that, if changed, will alter the vision for the product.
+
+## 4.5 Cost and Pricing
+
+Describe any relevant cost and pricing constraints, because these can directly impact the solution definition and implementation.
+
+# 5 Product Features
+
+This section describes the intended product features. Features provide the system capabilities that are necessary to deliver benefits to the users. Feature descriptions should be short and pithy, a key phrase, perhaps followed by one or two sentences of explanation.
+
+Use a level of abstraction high enough to be able to describe the system with a maximum of 25 to 50 features. Each feature should be perceivable by users, operators, or other external systems.
+
+## 5.1 Feature 1
+
+## 5.2 Feature 2
+
+# 6 Exemplary Use Cases
+
+[Optional] You may want to describe a few exemplary use cases, perhaps those that are architecturally significant or those that will most readily help the reader understand how  the system is intended to be used.
+
+# 7 Nonfunctional Requirements
+
+This section records other system requirements including nonfunctional requirements (constraints) imposed on the system (see Chapter 17).
+
+## 7.1 Usability
+
+## 7.2 Reliability
+
+## 7.3 Performance
+
+## 7.4 Supportability
+
+## 7.5 Other Requirements
+
+### 7.5.1 Applicable Standards
+
+List all standards the product must comply with, such as legal and regulatory, communications standards, platform compliance standards, and quality and safety standards.
+
+### 7.5.2 System Requirements
+
+Define any system requirements necessary to support the application. These may include the  host  operating systems  and  network  platforms,  configurations, communication, peripherals, and companion software.
+
+### 7.5.3 Licensing, Security, and Installation
+
+Licensing, security, and installation issues can also directly  impact the development effort. Installation requirements may affect coding or create the need for separate installation software.
+
+# 8 Documentation Requirements
+
+This section describes the documentation that must be developed to support successful deployment and use.
+
+## 8.1 User Manual
+
+Describe the intent of the user manual. Discuss desired length, level of detail, need for index and glossary, tutorial versus reference manual strategy, and so on. Formatting, electronic distribution, and printing constraints should also be identified.
+
+## 8.2 Online Help
+
+The nature of these systems is unique to application development since they combine aspects of programming and hosting, such as hyperlinks and web services, with aspects of technical writing, such as organization, style, and presentation.
+
+## 8.3  Installation Guides, Configuration, “Read Me” File
+
+A document that includes installation instructions and configuration guidelines is typically necessary. Also, a “read  me” file is often included as a standard component. The “read me” file may include a “What’s New with This Release” section and a discussion of compatibility issues with earlier releases. Most users also appreciate publication of any known defects and workarounds.
+
+## 8.4 Labeling and Packaging
+
+Defines the requirements for labeling to be incorporated into the code. Examples include copyright  and  patent notices,  corporate  logos,  standardized  icons,  and  other  graphic elements.
+
+## 9 Glossary
+
+The glossary defines terms that are unique to the program. Include any acronyms or abbreviations that need to be understood by users or other readers.

data/lib/assets/lib/clerq_doc.thor

@@ -0,0 +1,119 @@
+require 'clerq'
+require 'thor'
+require 'tmpdir'
+require_relative 'lib/colonize_repo'
+include Clerq::Repositories
+include Clerq::Entities
+include Clerq::Services
+
+# This thor file sample was created with purpose to show some examples
+# of using Pandoc for clerq reposiory publishing and even import souce
+# documents into a clerq repository ... `thor clerq:doc:grab`, `thor clerq:doc:publish`
+class ClerqDoc < Thor
+  include Thor::Actions
+  namespace 'clerq:doc'.to_sym
+
+  no_commands {
+    def eqid!(node)
+      counter = {}
+      node.to_a.drop(1).each do |n|
+        index = counter[n.parent] || 1
+        counter[n.parent] = index + 1
+        id = index.to_s.rjust(2, '0')
+        id = '.' + id unless n.parent == node
+        n.id = id
+      end
+    end
+  }
+
+  # Why does one need to grab the document?
+  #   it started in MS Word but the author decieded to pкoceed in Clerq
+  #   it is the source for the clerq project, SRS based on Vision?
+  #   something else?
+  # TODO provide -q/--query QUERY_STRING parameter
+  # TODO how about importing images?
+  desc 'grab FILENAME', 'Grab document and populate the clerq repository'
+  def grab(filename)
+    mdown = File.join(Dir.tmpdir, 'clerq.grab.md')
+    optns = [].tap{|o|
+      o << '--wrap=none'
+      o << '--atx-headers'
+      o << "#{filename}"
+      o << "-o #{mdown}"
+    }.join(' ')
+
+    `pandoc #{optns}`
+
+    on_error_callback = lambda {|err| puts err}
+    puts "Reading '#{mdown}'..."
+
+    # TODO handle query parameter
+    arry = ReadNode.(mdown, on_error_callback)
+    node = Node.new(id: '00', title: File.basename(mdown, '.md'))
+    arry.each{|n| node << n}
+    eqid!(node)
+
+    puts "Colonizing this repository..."
+    dir_counter = 0
+    src_counter = 0
+    on_create_dir = lambda {|dir| puts "Created '#{dir}' directory"; dir_counter += 1 }
+    on_create_src = lambda {|src| puts "Created '#{src}' file"; src_counter += 1 }
+
+    Dir.chdir(Clerq.src) { ColonizeRepo.(node, on_create_dir, on_create_src) }
+
+    msg = [].tap do |memo|
+      memo << "#{dir_counter} #{dir_counter == 1 ? 'directory' : 'directories'}" if dir_counter > 0
+      memo << "#{src_counter} #{src_counter == 1 ? 'file' : 'files'}" if src_counter > 0
+    end.join(' and ')
+
+    say "#{node.to_a.size} nodes from '#{filename}' imported to the repositroy. #{msg} created in the repository."
+  end
+
+  desc 'publish', 'Publishing final deliverables'
+  def publish
+    invoke :docx
+    invoke :html
+  end
+
+  desc 'html', 'Publish final deliverable in Html'
+  def html
+    source = File.join(Clerq.bin, Clerq.document + ".md")
+    target = File.join(Clerq.bin, Clerq.document + ".html")
+    optns = [].tap{|o|
+      o << '-s --toc --toc-depth 3'
+      o << "--resource-path #{Clerq.bin}"
+      o << "\"#{source}\""
+      o << "-o \"#{target}\""
+    }.join(" ")
+
+    `clerq build -t pandoc.md.erb`
+    `pandoc #{optns}`
+    say "\"#{target}\" created!"
+  end
+
+  desc 'docx', 'Publish final deliverable in Docx'
+  def docx
+    source = File.join(Clerq.bin, Clerq.document + ".md")
+    target = File.join(Clerq.bin, Clerq.document + ".docx")
+    sample = File.join(Clerq.bin, 'custom-reference.docx')
+
+    unless File.exist?(sample)
+      # produce a custom reference.docx
+      `pandoc -o #{sample} --print-default-data-file reference.docx`
+    end
+
+    optns = [].tap{|o|
+      o << '-s --toc --toc-depth 3'
+      o << '--from markdown+table_captions+implicit_figures'
+      o << "--reference-doc #{sample}"
+      o << "--resource-path #{Clerq.bin}"
+      o << "\"#{source}\""
+      o << "-o \"#{target}\""
+    }.join(" ")
+
+    `clerq build -t pandoc.md.erb`
+    `pandoc #{optns}`
+    say "\"#{target}\" created!"
+  end
+
+end