提交: 2e4e02bb2d2091e6387a49fbffc4240ebdf99a15 - MESS (hg)

Commit MetaInfo

• 修订版: 2e4e02bb2d2091e6387a49fbffc4240ebdf99a15 (tree)
• 时间: 2024-03-21 23:55:40
• 作者: Albert Mietus < albert AT mietus DOT nl >
• Commiter: Albert Mietus < albert AT mietus DOT nl >

Log Message

Agile-SIA (blog) is done. Publish STAGING

更改概述

• modified: SystemEngineering/RequirementsTraceability/index.rst
• modified: conf.py
• modified: requirements.txt
• add: .readthedocs.yaml
• add: SystemEngineering/AgileSIA/aBumper.jpg
• add: SystemEngineering/AgileSIA/demo/H1-needs.rst
• add: SystemEngineering/AgileSIA/demo/H2-authentic.rst
• add: SystemEngineering/AgileSIA/demo/H3-exact.rst
• add: SystemEngineering/AgileSIA/demo/H4-plastic.rst
• add: SystemEngineering/AgileSIA/demo/H5-HowToChoose.rst
• add: SystemEngineering/AgileSIA/demo/index.rst
• add: SystemEngineering/AgileSIA/goal/5chapters.rst
• add: SystemEngineering/AgileSIA/goal/index.rst
• add: SystemEngineering/AgileSIA/index.rst
• add: SystemEngineering/AgileSIA/notes/index.rst
• add: SystemEngineering/AgileSIA/notes/trace.rst

差异

diff -r 125e74b66eac -r 2e4e02bb2d20 .readthedocs.yaml
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/.readthedocs.yaml	Thu Mar 21 15:55:40 2024 +0100
@@ -0,0 +1,23 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  apt_packages:
+    - python3-sphinxcontrib.plantuml
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: conf.py
+
+# We recommend specifying your dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+  - requirements: requirements.txt
\ No newline at end of file

diff -r 125e74b66eac -r 2e4e02bb2d20 SystemEngineering/AgileSIA/aBumper.jpg
Binary file SystemEngineering/AgileSIA/aBumper.jpg has changed

diff -r 125e74b66eac -r 2e4e02bb2d20 SystemEngineering/AgileSIA/demo/H1-needs.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/SystemEngineering/AgileSIA/demo/H1-needs.rst	Thu Mar 21 15:55:40 2024 +0100
@@ -0,0 +1,123 @@
+.. Copyright (C) ALbert Mietus; 2023
+
+.. _SIA-demo-H1:
+
+=============================
+1) The Bumper of a Muscle Car
+=============================
+
+
+.. seealso::
+   This *first* chapter of the SIA is about requirements. Talk to **all** stakeholders, order and list **all** needs.
+   The client (ProductOwner) should react with: “*Yes, this the bumper we need*”.
+
+   -- :ref:`AgileSIA-5chapters`
+
+.. Caution::
+
+   * We mix the (shortened) text in this SIA with tips for the apprentice(s).
+     |BR|
+     Don’t do that in a genuine SIA.
+   * We use an “interview style” for some needs to clarify the several demand types,
+     |BR|
+     You will not do that in most SIAs.
+
+Assignment
+===========
+
+The client’s demand is simple:
+
+.. demo:: Make a bumper
+   :ID: BUMPER
+   :tags: Bumper
+   :project: AgileSIA
+
+He reasons that whenever we are worth a penny,  we know how to deliver a bumper, know all the legal specs, etc.
+
+Requirements
+============
+
+.. tip:: As you probably guessed, not “any bumper” will do. So, spend some time on *requirements gathering*.
+
+.. req:: Build to impress
+   :ID: BUMPER_chrome
+   :links: BUMPER
+   :tags: Bumper
+   :project: AgileSIA
+
+   As it is a Muscle Car, it should impress ordinary people. They generally like *bling-bling*, shiny stuff. So
+   the car will have a lot of chrome. We mandate this for the bumper as well.
+
+.. req:: We are in a hurry
+   :ID: BUMPER_April1
+   :links: BUMPER
+   :tags: Bumper
+   :project: AgileSIA
+
+   We will race with this car on April 1! So, we need the bumper quickly. And we assume you know we need both bumpers
+   mounted before we can start regulation. So, plz deliver it as early as possible!
+
+.. tip:: Not all requirements are technical. Usually, there are also demands [#nf]_ on cost, duration, quality, etc. Above, you
+         find an example.
+
+
+.. req:: Front and Back
+   :ID: BUMPER_1is2
+   :links: BUMPER
+   :tags: Bumper
+   :project: AgileSIA
+
+   Even though we always speak about “the bumper” --like everybody else-- every car needs two bumpers: one at the front
+   and one at the back. And they are not the same!
+
+   So, whenever we ask for one, plz deliver both! Although, I assume you already know that. ...
+
+.. tip::
+
+   This :need:`BUMPER_1is2` need is trivial. At least for some. But when your solution has it wrong is costly.
+   |BR|
+   Once in a while, a client will read a triviality and correct it. Then you saved even more.
+
+   Remember: the goal of this chapter is simple: *Make sure you solve the right problem*.
+
+.. req:: Impress me
+   :ID: BUMPER_SafetyImago
+   :links: BUMPER
+   :tags: Bumper
+   :project: AgileSIA
+
+   We build a luxury, high-end car. Our clients like to be impressed. Surely we don’t want to spend a fortune on a
+   bumper, but it shouldn't be cheap. Also, we prefer to give our clients a safe & secure car. So make sure that the
+   bumpers are not only regulation-safe but also “visualise” that!
+
+.. req:: Give me options
+   :ID: BUMPER_Green
+   :links: BUMPER
+   :tags: Bumper
+   :project: AgileSIA
+
+   This is our first eco-friendly muscle car; we used to be “petrol heads”. -- therefore we call it *”Green”*.
+   |BR|
+   Saying that, as the chief project manager, it worries me too.  We have so many things to do, there are so many
+   project risks, and we can’t afford to delay. Therefore, I’m very happy about your offer to help me with all those
+   non-core items.
+
+   What I’m basically saying is: “Give me options”. When you can deliver faster or find creative solutions, I am
+   interested --even when it costs more. Then, I can give you more components and remove some risk from my planning.
+
+.. tip::
+
+   For this exercise, we stop here with the demands. You should now have a quite complete image of the bumper that is
+   needed. And the (non-technical) demands for this mini-project.
+
+   .. warning:: You can now continue with the next page, chapter: :ref:`SIA-demo-H2`.
+      |BR|
+      **OR,** you can think for a moment to find a few  creative solutions that fit all needs -- Give it a try!
+
+-----
+
+.. rubric:: footnotes
+
+.. [#nf]
+   Experienced architects will tell you that the non-technical *needs* are the most important ones. Typically, an
+   architecture is driven by those “*non-functionals*”.

diff -r 125e74b66eac -r 2e4e02bb2d20 SystemEngineering/AgileSIA/demo/H2-authentic.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/SystemEngineering/AgileSIA/demo/H2-authentic.rst	Thu Mar 21 15:55:40 2024 +0100
@@ -0,0 +1,41 @@
+.. Copyright (C) ALbert Mietus; 2023
+
+.. _SIA-demo-H2:
+
+=========================
+2) The Authentic Solution
+=========================
+
+.. seealso:: This *second* chapter of the SIA contains the first of the typical three solutions. It will resolve **all**
+   needs as demanded in :ref:`The Problem analysis <SIA-demo-H1>`.
+   |BR|
+   But in another way than in “:ref:`SIA-demo-H3`” or “:ref:`SIA-demo-H4`”. *'Other'*, as in providing other business
+   needs. 
+
+   -- :ref:`AgileSIA-5chapters`
+
+
+Outline
+=======
+
+The basic idea of this proposal is to shop for a second-hand (set of) bumper(s).  We assume finding the Oldsmobile kind
+of bumpers is easy.  They are doubtless bent or rusty, but we can fix that.
+
+A huge advantage is they adhere to the classic ‘70-image of the typical muscle car. Would it be great to reuse the bumpers
+of a `1966 Pontiac GTO <https://en.wikipedia.org/wiki/Pontiac_GTO>`__?
+
+Pros & Cons
+===========
+
+* The cost of those bumpers is low, depending on their quality. A bit of restoration work will be needed, but nothing we
+  can't handle.
+* This solution fits the current “one of a kind” demands. It will not scale to mass production.
+* This *reuse* approach might fit nicely in the new “green, environmentally” concept.
+* As we need to search for (existing) bumpers, it is hard to predict exactly when we will find one (actually: 2).
+* There is even a (slight) risk we can’t find one. It is advisable to choose another option as a backup.
+
+.. note:: Complete this yourself
+
+.. tip:: Even this very short introduction already shows we are communicating in “car language”, not into the details of
+         the solution.
+

diff -r 125e74b66eac -r 2e4e02bb2d20 SystemEngineering/AgileSIA/demo/H3-exact.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/SystemEngineering/AgileSIA/demo/H3-exact.rst	Thu Mar 21 15:55:40 2024 +0100
@@ -0,0 +1,64 @@
+.. Copyright (C) ALbert Mietus; 2023
+
+.. _SIA-demo-H3:
+
+=====================
+3) The Exact Solution
+=====================
+
+.. seealso::
+
+
+   This (*third*) chapter of the SIA presents an alternative solution that fulfils **all** :ref:`requirements
+   <SIA-demo-H1>` again. It takes different factors and perspectives on their importance and priorities into
+   consideration.
+   |BR|
+   Where ":ref:`SIA-demo-H2`" is creative, this one is more classical.  The next one, “:ref:`SIA-demo-H4`”, will be
+   completely different again.
+
+   * :ref:`AgileSIA-5chapters`
+
+
+Outline
+=======
+
+We can develop a brand-new “chrome bumper” with the required old style. It gives the looks and robust image you are
+looking for, and we can make it fit exactly. It's not just the size or width of the car that matters, but also all the
+bolts and nuts that are needed.
+|BR|
+That might even help to assemble the car quickly and easily.
+
+Pros & Cons
+===========
+
+* It will always fit, but it requires a lot of manual labour, which makes it expensive.
+* Working with chrome is complex; it needs time to “Stabilise” (compare it with paint that has to dry).  That rest
+  period costs nothing but affects the (overall) planning.
+* Roughly, we need 13 steps, with (on average) a week between
+  |BR|
+  Note: this is not applicable for :math:`{\alpha}`- and :math:`{\beta}`-versions; they are faster.
+
+  * This option is scalable: more bumpers for many cars are possible.
+
+
+.. attention:: This demo is small, we skip a lot of (relevant) details.
+
+   For example, we *mention* the “assembly” topic and address the location of the bolts, nuts, and holes,  but only very
+   slightly.
+
+   An SIA (even an agile one) frequently has sub-chapters on those (functional) slices, to be introduced in
+   Chapter 1, or ’in’ one of the solutions. That mostly depends on how generic the “slice’ is for the solutions.
+
+   .. tip:: In the workshop, we go into more detail.
+
+      In this “bumper example” we might handle ‘slices’ like: ‘Mounting/Assembling’, ‘Reliability’, and ‘Validation of the
+      complete car’; depending on the audience.
+      |BR|
+      We can also use more software-relevant topics, directly. Like ‘does a solution fit in the existing (CI/CD) pipeline’,
+      ‘is training needed’, etc.
+
+   To say something cleaver, including the effect on cost, duration, risks, etc a (prematurely) design may be
+   needed -- I didn't (nor can't) do it as I’m not a mechanic.
+   |BR|
+   But remember: a SIA is not a design document! Design (whiteboard style) just enough to underpin your
+   statements. Don’t present it to your stakeholders, you only will annoy them. Unburden them!

diff -r 125e74b66eac -r 2e4e02bb2d20 SystemEngineering/AgileSIA/demo/H4-plastic.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/SystemEngineering/AgileSIA/demo/H4-plastic.rst	Thu Mar 21 15:55:40 2024 +0100
@@ -0,0 +1,50 @@
+.. Copyright (C) ALbert Mietus; 2023
+
+.. _SIA-demo-H4:
+
+====================
+4) Plastic Fantastic
+====================
+
+.. seealso:: This third solution, in chapter-4, is again a completely different approach to achieving the same
+   :ref:`needs <SIA-demo-H1>`.
+   |BR|
+   Whether you like it, or prefer :ref:`SIA-demo-H2` or :ref:`SIA-demo-H3`, is not relevant! That topic is not
+   part of the (all) solutions,  see the next (and last) chapter “:ref:`SIA-demo-H5`” for that!
+
+   -- :ref:`AgileSIA-5chapters`
+
+
+Outline
+=======
+
+As might know, we have a department that can “3D print” big plastics, including standard bumpers -- we deliver hundreds
+of them, for the aftermarket. Using this facility we can create safe, secure bumpers in any shape and size, in hours!
+|BR|
+Although almost any colour (combination) of plastics is possible (making it robust, as the colour is “inside), it is not
+very shiny. But we can add a “chrome finish”.
+
+This solution has several benefits. It is cost-effective and quick (far better than any other solution). But most
+important, it makes it easy to meet formal regulations (e.g. crash tests) as they are pre-validated. Combined with the
+great flexibility in mounting points, it makes assembling and validating the car easy.
+
+
+Pros & Cons
+===========
+
+* It is fast, fast, fast. We can deliver the first version next week. It’s also cost-effective: An extra “try-out” version
+  (not shiny) cost virtually nothing.
+* Also, assembling and validation become easy (see above).
+* It does meet all requirements --but it is a plastic solution, not a metal one. Plastic bumpers are generally
+  considered more secure  than metal, but your bumper magnets will not stick!
+* We can use this option as the backup of :ref:`SIA-demo-H2`.
+* We can also provide this option as a first, fast option and switch to another one whenever this one isn't “shiny
+  enough”. 
+  |BR|
+  (in this case, we need to switch in sprint- 2 or -3; otherwise, we have to replan).
+
+.. note:: Again, this is just an outlook for the chapter. But we keep it (extra) short for training goals.
+
+.. tip:: Can you see that the author is enthusiastic about this option?
+
+   .. caution::  Being enthusiastic is fine, but avoid the pitfall of “advertising”!

diff -r 125e74b66eac -r 2e4e02bb2d20 SystemEngineering/AgileSIA/demo/H5-HowToChoose.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/SystemEngineering/AgileSIA/demo/H5-HowToChoose.rst	Thu Mar 21 15:55:40 2024 +0100
@@ -0,0 +1,76 @@
+.. Copyright (C) ALbert Mietus; 2023
+
+.. _SIA-demo-H5:
+
+================
+5) How To Choose
+================
+
+.. seealso:: This *last* chapter is a short overview and/or tips on “**How** to choose”.
+
+   .. Caution:: Don’t advise on which solution is best!
+
+      Plz, do not get trapped in the pitfall to advise which solution *is* the best-- all should be ‘great’.
+      But *‘great’*, for other (business) reasons. Some are cheaper, some are faster, etc.
+
+      You merely advise on how the PO (client/...) shall select one of the solutions. “When T2M is most important, ...”,
+      or “When you target the top market, ...”, etc.
+
+   -- :ref:`AgileSIA-5chapters`
+
+We have presented three completely different solutions, each with its pros & cons. All do fulfil all needs as
+given in the 1ste chapter [:ref:`SIA-demo-H1`].
+|BR|
+Now, it is time to decide which one you prefer to continue with -- as a polite reminder: [:need:`BUMPER_April1`]. So, hope
+for a quick decision.
+
+Therefore, we present some tips.
+
+Tips
+====
+
+Which requirements are most prominent
+-------------------------------------
+
+Even though all requirements are met in every solution, some needs might have a bit more weight. So, let’s go over the
+most relevant ones.
+
+.. rubric:: :need:`BUMPER_chrome` & :need:`BUMPER_SafetyImago`
+
+When we like to impress on looks, the “Oldsmobile fenders” [:ref:`SIA-demo-H2`] beets all other solutions. Whereas
+[:ref:`SIA-demo-H4`] is the most safe solution.
+
+The brand-new chrome solution [:ref:`SIA-demo-H3`] is a nice combination for both requirements: safe and shiny.
+
+.. rubric:: :need:`BUMPER_April1`
+
+Solution “:ref:`SIA-demo-H2`” involves finding a second-hand “Oldsmobile bumper”. This should be easy but has a risk on
+timing. So, whenever we like to minimize risk, this solution isn’t preferable.
+|BR|
+Whereas the high-volume [:ref:`SIA-demo-H4`] option is very, very fast and has no risk of meeting the deadline at all;
+therefore we even mentioned it as a backup scenario.
+
+.. rubric::  :need:`BUMPER_Green`
+
+As the bumper is important but not the most expensive part, you can also consider to play on safe. For example, use the
+cost-effective fast [:ref:`SIA-demo-H4`] solution as a backup, and select one of the other two as the main solution.
+|BR|
+This guarantees a good bumper on time. And enables a risk-free great option.
+
+.. tip:: Skip :need:`BUMPER_1is2`
+
+   It’s obvious, two bumpers are needed. All solutions are in harmony here. So the is no need to handle it here.
+
+Other factors
+-------------
+
+.. rubric:: scalable & future
+
+Although it, is not a need, this ‘first eco-friendly muscle car’ is a first. And we assume (many) more will
+follow. Therefore we spend a few words on that too.
+
+[:ref:`SIA-demo-H3`] & [:ref:`SIA-demo-H4`] are the most scalable. There is no upper limit on the number of bumpers we
+can deliver.
+|BR|
+Price-wise, the plastic solution is cheaper. However, the piece price of a (new, labour-intensive) chrome bumper will
+go down when volume rises.

diff -r 125e74b66eac -r 2e4e02bb2d20 SystemEngineering/AgileSIA/demo/index.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/SystemEngineering/AgileSIA/demo/index.rst	Thu Mar 21 15:55:40 2024 +0100
@@ -0,0 +1,40 @@
+.. Copyright (C) ALbert Mietus; 2023
+
+.. _SIA-demo:
+
+*******************
+Demo: Make a bumper
+*******************
+
+This demo is (far) outside the typical software sphere to help you focus on the Agile SIA itself. With no typical
+software-engineering fixations, you shouldn't be distracted by with SW-details.
+
+At the same time, it is a technical challenge.
+|BR|
+I assume you are familiar with this common car background.
+
+We use ':ref:`AgileSIA-5chapters`, but each chapter is extremely short. Please make your next SIA short too, but with
+some body text to make it more readable. 
+
+Before you write your 1st genuine Agile SIA, I advise you to practice on a software engineering topic. My training has
+one, but it isn’t published.
+
+
+.. hint:: Background
+
+   In this demo, our client is building an impressive **Green Muscle Car**. We just advised him to put his best men
+   (and women) on the electric engine, the battery and the breaks. We also convinced him to trust us for *non-core
+   components*, like the luxury, leader steering wheel, and the bumpers.
+
+   He agreed and asked us to write an Agile SIA for the bumper.
+
+
+.. rubric:: Content
+.. toctree::
+   :maxdepth: 3
+
+   H1-needs
+   H2-authentic
+   H3-exact
+   H4-plastic
+   H5-HowToChoose

diff -r 125e74b66eac -r 2e4e02bb2d20 SystemEngineering/AgileSIA/goal/5chapters.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/SystemEngineering/AgileSIA/goal/5chapters.rst	Thu Mar 21 15:55:40 2024 +0100
@@ -0,0 +1,92 @@
+.. _AgileSIA-5chapters:
+
+The 5 chapter template
+======================
+
+It might help to use the following template to understand the goals of the SIA. And assist in writing a sound one.
+
+An SIA usually consists of only five chapters:
+
+1. The Problem Analyse
+----------------------
+
+This is a bit like a Requirements Gathering phase. Usually one has to communicate with all stakeholders (or read
+their inputs) to thoroughly understand and list their needs.  All the requirements and desires should be listed in
+natural language and presented in a logical manner [#NoInterview]_.
+|BR|
+There is no need to select or prioritise the demands at this stage.
+
+In many cases, the stakeholders have already expressed their input and one uses mainly other (“higher”) documents
+as input. Remember, however, it’s about what the stakeholders want, not about the documents themselves.
+|BR|
+Do not “copy” all those demands. Just mention them, link to the source and summarise them such that the document is
+readable.
+
+More often than not, this is a short chapter, maybe a few pages. The goal is that the PO and all stakeholders
+say: “Yes, that is exactly what we need” [#check]_.
+
+2.  Solution A
+--------------
+
+It gives a highlight of the first presented (design) option, without explaining the design. Just enough so that the
+PO (and other stakeholders) understand it -- there is no need that anybody can implement it already.
+
+Then, the cost, risk, duration and other relevant topics (for the stakeholders) are explained.
+|BR|
+Again, keep it simple and global. Don’t try to convince the PO; (s)he will (should) trust your analysis.
+
+Optionally you can present some sub-options. But don’t go into details. Only sub-options that are relevant for the
+PO are relevant.
+
+3. Solution B
+--------------
+
+Same as above, but (completely) different.
+|BR|
+Sometimes a feature can be split into several functional “slices” [#cake]_.
+
+Different solutions may come with different slices, but we can also have common ones. Then, introduce them early, and
+refer to them in the next solution(s).  Make it explicit which slices are (partially) common and which not.
+|BR|
+Despite that slices can be common, they may have other effects on investments (costs etc), risk or other business
+values Therefore, I prefer to write out those aspects in each solution. Often assisted with a phrase as *“a bit
+more/better/... than in ..”*
+
+4. Solution C
+-------------
+Again, another way for the same result [#cents]_.
+
+5. Summary/Overview
+-------------------
+
+This short chapter lists the relevant differences (for the PO/stakeholders) between the solutions, often in a table.
+
+It frequently also advice on **how** to select the best option. This is to guide the PO.
+|BR|
+By example:
+
+* *“Solution A has the shortest T2M, although it is twice as expensive”*.
+* *“When future extensibility is key, solution B offers the most flexibility”*.
+* *“Solution C has the main benefit that it has many slices, each can be realised independently in a series of
+  sprints”*.
+* *“For the same reason, solution C can be implemented in 10 concurrent teams, keeping them fully loaded*
+  |BR|
+  (especially as we have the risk that two teams run out of work).”
+
+-----
+
+.. rubric:: Footnotes & Links
+
+.. [#NoInterview] Plz, don’t make it a conversation report. Don’t use stakeholder order. And always use your own words.
+.. [#Check] Typically this 1st chapter is reviewed early. This chapter is also a check: When the team misunderstands the
+   feature, it is better to fail fast.
+
+.. [#cake] A cake is (typically) cooked bottom-up and consumed left-to-right. Even though the sum of the layers and the
+   sum of the slices are equal, the effect differs. I often use this analogy and will write a blog about it
+   “soon”. For now, plz just remember it does differ and get used to the term:-)
+
+.. [#cents] Be “`Pound Wise and Penny Foolish <https://www.dictionary.com/browse/penny-wise-and-pound-foolish>`__”!
+   |BR|
+   Nobody is (or should be) interested in a solution that differs only in a few (pre)cents. Not in an (upfront) SIA
+   document. Unless, of course, when that percentage is a relevant business topic.
+

diff -r 125e74b66eac -r 2e4e02bb2d20 SystemEngineering/AgileSIA/goal/index.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/SystemEngineering/AgileSIA/goal/index.rst	Thu Mar 21 15:55:40 2024 +0100
@@ -0,0 +1,100 @@
+.. Copyright (C) ALbert Mietus; 2023, 2024
+
+**********
+Objectives
+**********
+
+The goal of an SIA is to *analyse* the impact of a feature (or change) and *apprise the PO* of the options he has to
+achieve it.  It typically results in a document --but the document is *not* the goal (and shouldn't be)!
+
+As we will see below, the goal of the SIA is to guide the next development steps: Does it bring (business) value?
+*(typically: yes)* and what is the best option to realise it? After making those two decisions, the impact analysis
+--and the SIA document itself-- quickly loses its value.
+|BR|
+In that view, the write-a-document part can even be considered a waste! That is not what I recommend, however. A written
+document is also helpful for discussing and reviewing the SIA.
+
+
+Business value
+==============
+
+Before one can decide whether and how a feature brings value, one needs insight into the necessary investment [#estimate]_
+This is not only (development) *costs* (sw: mostly man-hours). Usually, *duration* (Time-2-Realize, or
+Time-2-Marked) and *risks* (e.g. to introduce bugs) are as important. Depending on the ecosystem, other topics should be
+addressed too.
+
+Generally, there are multiple (technical) means to accomplish the same innovation [#ISW]_, [#OneShot]_. The SIA should
+offer a few (typically: 3 main) solutions, possibly with variants. They all fulfil the demands but differ in
+quality, luxury, and more relevant for the PO: primary value and investments.
+
+Avoid common mistakes
+=====================
+
+* A SIA can get too technical and appear more like a design document, which makes it difficult for people to understand
+  the impact. And to expenses to write.
+
+  As a consequence, deciding not to go forward becomes impractical.
+  |BR|
+  At the same time, it’s often “too much work” to offer multiple solutions. Then, there is nothing to choose. --making
+  the SIA useless.
+
+  * A design (phase & document) may be needed --even in a lean, agile approach. It is planned after the SIA.
+  * Remember, should the PO lower the priority --based on the Agile SIA-- the design effort has become a waste.
+  * Even when not: When the SIA present three options and so three designs are made, we use only one.
+
+* Not thinking about **design options**.
+  |BR|
+  Sometimes only one option is presented. Then, the PO can’t choose. But usually, it implies somebody else has made the
+  choice (implicitly). That is not the role of the team.
+
+* No upfront **design thinking**. This is the other extreme of the first mistake (too much design), and as bad.
+  |BR|
+  Even though the document shouldn't be “too technical” (*as it should focus on business value, and in the language of the PO*), that
+  does not imply the team has to think about the design. A bit of “whiteboard design” is needed, to estimate the cost
+  (etc) of that option.
+
+  * There is no need to convert those (3) design sketches into real designs and present them in the SIA.
+  * Only the effect of that design is presented to the PO (and so globally described in the SIA)
+
+  .. note:: Remember those sketches
+
+     It is wise to store all those sketches, and possibly some notes, for later. Most likely one of the three will be
+     needed in an upcoming phase/sprint. Then it (only one) will be converted into a real design and worked out.
+     |BR|
+     In a typical lean, agile approach, those provisional designs are stored as a photo in a wiki, along with the
+     notes.
+
+Use the 5 chapters template
+===========================
+
+As we present in :ref:`AgileSIA-5chapters`, an (agile, lean) SIA has five chapters, only 5!
+|BR|
+However, it not the exact number that counts -- some prefer to combine the 3 “solutions chapters” is a single chapters,
+other may varie a bit on number of solutions, or the place of sub-chapters.
+
+Still, using that template (as used in :ref:`SIA-demo`) will typically result in a nice SIA.
+
+
+
+-----
+
+.. rubric:: Footnotes & Links
+
+.. [#estimate] In that (limited) view, an SIA is like a complicated planning session.
+   |BR|
+   Depending on (e.g.) costs, the PO may place the feature high, or low, on the prioritised backlog.
+
+.. [#ISW] “*It Should Work*” is a common baseline. All presented options should work, as nobody will ever select one
+   that doesn't. But it doesn't need to be perfect (see below).
+
+.. [#OneShot] Mostly, software should be maintainable. *“Clean Code”* has business value in the long run.
+   |BR|
+   However, once and a while we need “One Shot” [#OneShot2]_ code, where this is less needed. Then, the PO may decide to
+   go for a (cheaper) option that has less quality.
+
+.. [#OneShot2] As an example: migration “scripts” to update data from version `x.1(a)` to `x.1(b)`  will never be used
+   again after the update. Or a “Proof of Concept”; typically that code is written fast, to demonstrate the ability, then
+   replaced by “real code” and thrown away.
+   |BR|
+   That kind of software is often written in “another language”. The risk that nobody can maintain it is absent.
+

diff -r 125e74b66eac -r 2e4e02bb2d20 SystemEngineering/AgileSIA/index.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/SystemEngineering/AgileSIA/index.rst	Thu Mar 21 15:55:40 2024 +0100
@@ -0,0 +1,61 @@
+.. Copyright (C) ALbert Mietus; 2023, 2024
+
+.. sidebar:: Workshop & Blog
+
+   Welcome to the condensed "blog edition" of my workshop `“Using & Writing an Agile SIA”`.
+   |BR|
+   If you're eager for the full experience, don't hesitate to reach out for the complete workshop.
+
+.. _AgileSIA:
+
+============
+An Agile SIA
+============
+
+.. post:: 2024/03/21
+   :tags: SysEng, Modernize
+   :category: lecture
+   :language: en
+
+   The **SIA** -- an acronym for *System* (or Software) *Impact Analysis* -- is an often used approach to get insight into
+   the costs, risks, and possibilities of implementing a feature. It should result in a readable document to
+   decide whether it adds value to implement that feature and offer options on how
+   |BR|
+   But is also a document that is repeatedly incorrectly used.
+
+   The classical SIA isn't very Lean nor Agile; certainly not when it became an (upfront) design document, as
+   often ...
+   |BR|
+   On second thought, a good SIA is lean and agile. A short, up-front *“think ahead”* document makes it possible
+   to postpone details to future sprints and assist the Product Owner in picking the right solution without adding
+   costs.
+
+   Let’s study how we can write an Agile SIA. One with business value.
+
+
+.. admonition:: *“a Bumper”* is **not any** Bumper (demo)
+
+   .. image:: ./aBumper.jpg
+      :width: 33%
+      :align: right
+
+   * In this workshop, we design ‘a bumper’. Or actually: we write the SIA for it.
+   * By using a not-software example, it is easier to *not focus* on the technicalities that shouldn't be in the SIA
+     anyhow
+   * For mechanical engineers: I’m probably oversimplifying and missing relevant details. Sorry about that:-)
+     |BR|
+     I welcome feedback to improve!
+   * The “bumper image” is from a `1967 Citroen 2CV
+     <https://commons.wikimedia.org/wiki/File:1967_Citroen_2CV_-_front_bumper_detail_-_16000647651_(cropped).jpg>`__,
+     which is cropped and `reused <https://www.flickr.com/photos/7467877@N07/16000647651/>`__ as permitted. Thanks!
+
+
+.. rubric:: Content
+.. toctree::
+   :maxdepth: 2
+
+   goal/index
+   goal/5chapters
+   demo/index
+   notes/index
+

diff -r 125e74b66eac -r 2e4e02bb2d20 SystemEngineering/AgileSIA/notes/index.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/SystemEngineering/AgileSIA/notes/index.rst	Thu Mar 21 15:55:40 2024 +0100
@@ -0,0 +1,13 @@
+.. Copyright (C) ALbert Mietus; 2023
+
+.. _SIA-notes:
+
+*******************
+Notes
+*******************
+
+.. toctree::
+   :glob:
+   :maxdepth: 2
+
+   *

diff -r 125e74b66eac -r 2e4e02bb2d20 SystemEngineering/AgileSIA/notes/trace.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/SystemEngineering/AgileSIA/notes/trace.rst	Thu Mar 21 15:55:40 2024 +0100
@@ -0,0 +1,9 @@
+Tracing Bumper needs
+====================
+
+
+Just as a service, we present a (generated) overview of the requirements for the bumper needs
+
+.. needflow::
+   :tags: Bumper
+   :filter: 'AgileSIA' in project

diff -r 125e74b66eac -r 2e4e02bb2d20 SystemEngineering/RequirementsTraceability/index.rst
--- a/SystemEngineering/RequirementsTraceability/index.rst	Fri May 12 18:59:29 2023 +0200
+++ b/SystemEngineering/RequirementsTraceability/index.rst	Thu Mar 21 15:55:40 2024 +0100
@@ -8,9 +8,9 @@
 
 .. post:: 2020/02/15
    :tags: SysEng
-   :category: lecture
-   :location: Vianen
-   :language: en
+   :category: lecture 
+   :location: Vianen 
+   :language: en 
 
    :study-time: 1 hour
 

diff -r 125e74b66eac -r 2e4e02bb2d20 conf.py
--- a/conf.py	Fri May 12 18:59:29 2023 +0200
+++ b/conf.py	Thu Mar 21 15:55:40 2024 +0100
@@ -1,12 +1,13 @@
 # Copyright (C) ALbert Mietus, SoftwareBeterMaken.nl; 2017- 2023 Part of my MESS project
 # -*- coding: utf-8 -*-
 
+DEBUG=False
+
 # read STD config ...
 #==========================================
 import sys; sys.path.append('_std_settings/conf')
 from std_conf import *
 
-
 # For sphinx.ext.autodoc':
 import os.path; sys.path.append('pyMESS/training/dPID')
 
@@ -22,16 +23,19 @@
 # Overrule std_conf, where needed
 #================================
 
-#html_title = project + " | " + release # DEFAULT: '<project> v<revision> documentation' -- Strip "documentation"
+html_title = project + " | " + release # DEFAULT: '<project> v<revision> documentation' -- Strip "documentation"
 
+html_sidebars = {
+    '**': [ 'recentposts.html', 'tagcloud.html', 'postcardHeader.html'],
+}
 
 
 # ABlog
 #------
 extensions.append('ablog')
 extensions.append('sphinx.ext.intersphinx') # GAM: workaround?
-import ablog; templates_path.append(ablog.get_html_templates_path())
-fontawesome_link_cdn = "http://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css"
+
+fontawesome_link_cdn = "https://use.fontawesome.com/releases/v5.0.10/css/all.css"
 post_date_format = '%Y/%m/%d'
 post_date_format_short = '%Y/%m'
 
@@ -50,15 +54,12 @@
 disqus_pages = True                                                 # All pages have a disqus-section
 disqus_drafts = False                                               # .. but the draft (blog) pages (.. post:: without date )
 
-html_sidebars = {
-    '**': [ 'recentposts.html', 'tagcloud.html', 'postcardHeader.html'],
-}
 
 
 
 html_static_path.append('_slides')
 
-if False:
+if DEBUG:
     print("Debug: show all packages:")
     import os
     os.system("pip list")

diff -r 125e74b66eac -r 2e4e02bb2d20 requirements.txt
--- a/requirements.txt	Fri May 12 18:59:29 2023 +0200
+++ b/requirements.txt	Thu Mar 21 15:55:40 2024 +0100
@@ -1,6 +1,8 @@
+sphinx==6.2.1
 ablog
-sphinxcontrib-plantuml==0.23
+#sphinxcontrib-plantuml==0.23
+sphinxcontrib-plantuml
 sphinxcontrib-needs==0.7.9
+sphinxcontrib-needs
 sphinx_rtd_theme
-sphinx==4.5.0
-urllib3==1.26.4
+#urllib3==1.26.4