#1 moved all objectives to separate pages

EKGF · Feb 3, 2022 · eae552c · eae552c
1 parent 2453490
commit eae552c
Show file tree

Hide file tree

Showing 16 changed files with 182 additions and 138 deletions.
diff --git a/Makefile b/Makefile
@@ -66,9 +66,10 @@ endif
 	pip install --upgrade mkdocs
 	pip install --upgrade mkdocs-material
 	pip install --upgrade mkdocs-localsearch
-	pip install --upgrade mdx-spanner
+	pip install --upgrade mkdocs-include-markdown-plugin
 	pip install --upgrade mkdocs-awesome-pages-plugin
 	pip install --upgrade mkdocs-macros-plugin
+	pip install --upgrade mdx-spanner
 	pip install --upgrade markdown-emdash
 
 .PHONY: docs-build

diff --git a/docs/.pages.yaml b/docs/.pages.yaml
@@ -1,3 +1,4 @@
 nav:
   - index.md
-  - products
+  - objective
+  - product
diff --git a/docs/index.md b/docs/index.md
@@ -55,141 +55,10 @@ a building block with which other use cases can be constructed.
 The Use Case Tree Method is a practice that has been developed and
 used for many EKG use cases that are running in production.
 
-The primary reasons for creating a Use Case Tree are:
+{%
+include-markdown "objective/index.md"
+start="<!--objectives-index-start-->"
+end="<!--objectives-index-end-->"
+%}
 
-1. **Know what the business wants**.<br/>
-    Know exactly what the business --- i.e. the customer or product owner
-    --- really needs, short-, mid- and long-term.
 
-    1. <u>Plan phase: Discover the business opportunities & business needs</u><br/>
-       One of the tasks during the planning phase of any new initiative
-       --- or iteration --- is to "Discover" the business opportunities &
-       needs:
-
-         - In non-technical terms.
-
-         - Without assuming anything about existing systems and "how
-           things are done today".
-
-         - Translate to "pure" functional requirements --- and "nice
-           to haves".
-
-         - Looking broad horizontally, thinking ahead. Mile wide, inch
-           deep at this stage.
-
-         - Let the business "dream a little" about "what could be"
-           and "what should be", so that future needs can be
-           identified and communicated --- without necessarily
-           committing to them (yet).
-
-         - Promote "thinking outside the box", encourage people to
-           not make any assumptions about what is technically possible
-           or not --- so often these assumptions unknowingly keep the
-           bar lower than it could be.
-
-    2. <u>Build phase: Translate requirements into an easy to 
-       understand model i.e. the Use Case Tree</u><br/>
-       "Contract with the business" i.e. the budget holder or
-       product owner. 
-       Every major change to any given use case in the 
-       Use Case Tree will have to be signed off by the 
-       appropriate product owner.
-
-         - Capture it as "meta-data" that will be part of the
-           EKG --- all the way to production.
-
-         - Capture it in such a way that "everything that we ever do"
-           is always directly or indirectly relatable to a use case
-           in the Use Case Tree.
-
-         - The business never loses sight on what happens with their
-           budget and agreed deliverables.
-           All reporting to the business occurs in the context of 
-           the agreed , even after delivery.
-
-2. **Bridge the traditional gap between Business & Technology**.
-
-    - Engage with the business, the product owner and get continuous
-      buy-in from the product owner during the life-cycle of the
-      agreed use cases.
-
-    - But not only with the product owner of the direct use case being
-      developed but also show to the business what other future needs
-      need to be considered.<br/>
-      For instance, if one use case e.g. "Legal Entities" needs
-      "workflows", would it make sense to invest a bit more effort
-      to then create a reusable workflow component that can also 
-      be used for many other use cases such as 
-      "Shareholding disclosure"?
-
-    - Yes, the customer is always right but the Use Case Tree 
-      shows to the customer that there are many other customers
-      (or future customers, in and outside the organization even)
-      and why it makes sense to prioritize reuse and how that not 
-      only could deliver more quality but also create more buy-in 
-      from peer stakeholders across the firm or even across the 
-      industry.
-
-        * In other words, do not select one product owner to be the
-          single stakeholder but also get other stakeholders of
-          neighboring or higher level use cases in the room, their
-          requirements may influence the reuse agenda and therefore
-          the roadmap. It may sound paradoxal but investing in reuse
-          will not slow things down but speed things up.
-
-3. **Best form of "expectation management"**, creating an agreed and
-    realistic strategic roadmap.
-
-4. **Foundational mechanism to create an ecosystem of reusable
-    components** for the EKG.
-
-5. **Avoids "boiling the ocean"** because the Use Case Tree and its
-    individual use cases define an agreed scope at the detail 
-    level (without becoming technical).
-
-    - Provides focus for the EKG Center of Excellence (CoE),
-      "cranking out" use cases one by one
-
-    - Ontology development will be focussed on delivering on the
-      requirements (user stories and concepts) of the agreed use cases
-      rather than ending up in philosophical exercise.
-
-6. **Provides a "map" of all knowledge, data and functionality** that
-    the EKG provides to the enterprise.
-    Which is not only useful for users of the EKG but also a necessity 
-    since all of these use cases are served by one platform -- albeit
-    distributed and federated etc -- there will be many stakeholders
-    with different agendas that would not care -- nor have to care --
-    about the wishes of the stakeholders in other use cases.
-    However, updates to one use case could potentially also
-    affect other use cases.<br/>That's why:
-    - <u>all changes & updates have to be done gradually, 
-      no ”big bang” releases</u> and
-    - <u>all inter-dependencies need to be really clear and
-      tested in-full automatically and continuously.</u>
-
-    So, for instance, when some sub-use case in a high-level use case is
-    also used in another high-level use case then a change that serves
-    the needs of one could potentially also affect the other and its
-    users. That's why we need the , to allow us to avoid any disruption
-    across the board.
-
-9. **Foundational structure for quality** since it enforces, requires
-    and enables 100% test coverage based on real business scenarios and
-    requirements.
-
-    - A use case has a life-cycle that starts with a name and a
-      description and ends[^1] with a fully detailed model of all
-      related concepts, personas, business outcomes, datasets,
-      ontologies, user stories and dependencies.
-      That model is all captured in the EKG itself which allows the
-      EKG to not only fully and thoroughly test things during
-      development time (build phase) but also in production
-      (run phase).
-      Which provides the level of quality that an EKG needs to
-      have to become truly able to support enterprise level 
-      strategic use cases.
-
-[^1]: Obviously, use cases can also be decommissioned after their life
-in producton so in fact there are more stages in the life-cycle of a
-use case
diff --git a/docs/objective/.pages.yaml b/docs/objective/.pages.yaml
@@ -0,0 +1,11 @@
+title: Objectives
+nav:
+  - know-what-the-business-wants.md
+  - Bridge the Gap: bridge-the-gap.md
+  - Manage Expectations: manage-expectations.md
+  - Enable Reuse: enable-reuse.md
+  - No boiling ocean: avoid-boiling-the-ocean.md
+  - capture-knowledge.md
+  - avoid-disruption.md
+  - increase-quality.md
+  - ...
diff --git a/docs/objective/avoid-boiling-the-ocean.md b/docs/objective/avoid-boiling-the-ocean.md
@@ -0,0 +1,8 @@
+# Avoid "boiling the ocean"
+
+Avoids ”boiling the ocean” because the Use Case Tree and its individual use cases
+define an agreed scope at the detail level (without becoming technical).
+
+- Provides focus for the Center of Excellence (CoE), ”cranking out” use cases one by one
+- Ontology development will be focussed on delivering on the requirements (user stories and
+  concepts) of the agreed use cases rather than ending up in philosophical exercise.
diff --git a/docs/objective/avoid-disruption.md b/docs/objective/avoid-disruption.md
@@ -0,0 +1,26 @@
+# Avoid Disruption
+
+[Capturing all knowledge in the organization](capture-knowledge.md)
+as much as technically possible is not only useful to enable a whole
+new league of use cases but is also a necessity since all of these 
+use cases are served by one platform --- albeit distributed and federated.
+Which means that there will be many stakeholders with different agendas
+that would not care --- nor should they have to care --- about the wishes 
+of the stakeholders in other use cases.
+
+However, updates to one use case could potentially also
+affect other use cases.
+
+That's why:
+
+- <u>all changes & updates have to be done gradually,
+  no ”big bang” releases</u> and
+- <u>all inter-dependencies need to be really clear and
+  tested, in-full, automatically and continuously.</u>
+
+So, for instance, when some sub-use case of a high-level use case is
+also used in another high-level use case then a change that serves
+the needs of one could potentially also affect the other and its
+users.
+That's why we need the Use Case Tree, to allow us to avoid any disruption
+across the board.
diff --git a/docs/objective/bridge-the-gap.md b/docs/objective/bridge-the-gap.md
@@ -0,0 +1,29 @@
+# Bridge the traditional gap between Business & Technology
+
+- Engage with the business, the product owner and get continuous
+  buy-in from the product owner during the life-cycle of the
+  agreed use cases.
+
+- But not only with the product owner of the direct use case being
+  developed but also show to the business what other future needs
+  need to be considered.<br/>
+  For instance, if one use case e.g. "Legal Entities" needs
+  "workflows", would it make sense to invest a bit more effort
+  to then create a reusable workflow component that can also 
+  be used for many other use cases such as 
+  "Shareholding disclosure"?
+
+- Yes, the customer is always right but the Use Case Tree 
+  shows to the customer that there are many other customers
+  (or future customers, in and outside the organization even)
+  and why it makes sense to prioritize reuse and how that not 
+  only could deliver more quality but also create more buy-in 
+  from peer stakeholders across the firm or even across the 
+  industry.
+
+    * In other words, do not select one product owner to be the
+      single stakeholder but also get other stakeholders of
+      neighboring or higher level use cases in the room, their
+      requirements may influence the reuse agenda and therefore
+      the roadmap. It may sound paradoxal but investing in reuse
+      will not slow things down but speed things up.
diff --git a/docs/objective/capture-knowledge.md b/docs/objective/capture-knowledge.md
@@ -0,0 +1,5 @@
+# Capture Knowledge
+
+The Use Case Tree **Provides a "map" of all knowledge, data and 
+functionality** that the EKG provides to the enterprise.
+Enabling a whole new league of use cases.
diff --git a/docs/objective/enable-reuse.md b/docs/objective/enable-reuse.md
@@ -0,0 +1,4 @@
+# Enable Reuse
+
+The Use Case Tree is a foundational mechanism to create an ecosystem of 
+reusable components for the EKG.
diff --git a/docs/objective/increase-quality.md b/docs/objective/increase-quality.md
@@ -0,0 +1,22 @@
+# Increase Quality
+
+The Use Case Tree is a foundational structure for quality 
+--- any kind of quality --- 
+since it enforces, requires and enables 100% test coverage 
+based on real business scenarios and requirements.
+
+- A use case has a life-cycle that starts with a name and a
+  description and ends[^1] with a fully detailed model of all
+  related concepts, personas, business outcomes, datasets,
+  ontologies, user stories and dependencies.
+  That model is all captured in the EKG itself which allows the
+  EKG to not only fully and thoroughly test things during
+  development time (build phase) but also in production
+  (run phase).
+  Which provides the level of quality that an EKG needs to
+  have to become truly able to support enterprise level
+  strategic use cases.
+
+[^1]: Obviously, use cases can also be decommissioned after their life
+in producton so in fact there are more stages in the life-cycle of a
+use case
diff --git a/docs/objective/index.md b/docs/objective/index.md
@@ -0,0 +1,14 @@
+# Index
+
+<!--objectives-index-start-->
+The primary reasons for creating a Use Case Tree are:
+
+1. [Know what the Business wants](know-what-the-business-wants.md)
+2. [Bridge the Gap](bridge-the-gap.md)
+3. [Manage Expectations](manage-expectations.md)
+4. [Enable Reuse](enable-reuse.md)
+5. [Avoid "boiling the ocean"](avoid-boiling-the-ocean.md)
+6. [Capture Knowledge](capture-knowledge.md)
+7. [Avoid Disruption](avoid-disruption.md)
+8. [Increase Quality](increase-quality.md)
+<!--objectives-index-end-->
diff --git a/docs/objective/know-what-the-business-wants.md b/docs/objective/know-what-the-business-wants.md
@@ -0,0 +1,50 @@
+# Know what the business wants
+
+Know exactly what the business --- i.e. the customer or product owner
+--- really needs, short-, mid- and long-term.
+
+1. <u>Plan phase: Discover the business opportunities & business needs</u><br/>
+   One of the tasks during the planning phase of any new initiative
+   --- or iteration --- is to "Discover" the business opportunities &
+   needs:
+
+    - In non-technical terms.
+
+    - Without assuming anything about existing systems and "how
+      things are done today".
+
+    - Translate to "pure" functional requirements --- and "nice
+      to haves".
+
+    - Looking broad horizontally, thinking ahead. Mile wide, inch
+      deep at this stage.
+
+    - Let the business "dream a little" about "what could be"
+      and "what should be", so that future needs can be
+      identified and communicated --- without necessarily
+      committing to them (yet).
+
+    - Promote "thinking outside the box", encourage people to
+      not make any assumptions about what is technically possible
+      or not --- so often these assumptions unknowingly keep the
+      bar lower than it could be.
+
+2. <u>Build phase: Translate requirements into an easy to
+   understand model i.e. the Use Case Tree</u><br/>
+   "Contract with the business" i.e. the budget holder or
+   product owner.
+   Every major change to any given use case in the
+   Use Case Tree will have to be signed off by the
+   appropriate product owner.
+
+    - Capture it as "meta-data" that will be part of the
+      EKG --- all the way to production.
+
+    - Capture it in such a way that "everything that we ever do"
+      is always directly or indirectly relatable to a use case
+      in the Use Case Tree.
+
+    - The business never loses sight on what happens with their
+      budget and agreed deliverables.
+      All reporting to the business occurs in the context of
+      the agreed , even after delivery.
diff --git a/docs/objective/manage-expectations.md b/docs/objective/manage-expectations.md
@@ -0,0 +1,3 @@
+# Best form of ”expectation management”
+
+Creating an agreed and realistic strategic roadmap.
diff --git a/docs/products/.pages.yaml → docs/product/.pages.yaml b/docs/products/.pages.yaml → docs/product/.pages.yaml
diff --git a/docs/products/index.md → docs/product/index.md b/docs/products/index.md → docs/product/index.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -54,6 +54,7 @@ extra:
     - icon: fontawesome/brands/github
       link: https://github.com/EKGF/use-case-tree-method
 plugins:
+  - include-markdown
   - search:
       prebuild_index: true
       lang:
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Best form of ”expectation management”

		Creating an agreed and realistic strategic roadmap.