diff --git a/docs/bets/Coding-Bets.md b/docs/bets/Coding-Bets.md index 888d0e47e..f10cc2eea 100644 --- a/docs/bets/Coding-Bets.md +++ b/docs/bets/Coding-Bets.md @@ -9,6 +9,7 @@ featured: element: 'Coding Bets' tags: - Bets + - Refactoring sidebar_position: 2 tweet: yes --- diff --git a/docs/complexity/Crystals-And-Code.md b/docs/complexity/Crystals-And-Code.md index 983b270a3..b0fedb3a5 100644 --- a/docs/complexity/Crystals-And-Code.md +++ b/docs/complexity/Crystals-And-Code.md @@ -8,6 +8,7 @@ featured: element: 'Crystals And Code' tags: - Complexity + - Refactoring sidebar_position: 2 tweet: yes --- diff --git a/docs/methods/Agile.md b/docs/methods/Agile.md index 0ee995c28..73e4a1945 100644 --- a/docs/methods/Agile.md +++ b/docs/methods/Agile.md @@ -2,6 +2,7 @@ tags: - Prototyping - Coding + - Pair Programming --- ![Draft](/img/state/draft.png) diff --git a/docs/methods/DevOps.md b/docs/methods/DevOps.md index 9b4272826..4f57af151 100644 --- a/docs/methods/DevOps.md +++ b/docs/methods/DevOps.md @@ -1 +1,6 @@ +--- +tags: + - Automation +--- + ![Draft](/img/state/draft.png) diff --git a/docs/methods/Lean.md b/docs/methods/Lean.md index bc61c2628..ec753a485 100644 --- a/docs/methods/Lean.md +++ b/docs/methods/Lean.md @@ -1,3 +1,7 @@ +--- +tags: + - Automation +--- ![Draft](/img/state/draft.png) diff --git a/docs/practices/Glossary-Of-Practices.md b/docs/practices/Glossary-Of-Practices.md index 4f4c0cedb..c31bf313e 100644 --- a/docs/practices/Glossary-Of-Practices.md +++ b/docs/practices/Glossary-Of-Practices.md @@ -77,7 +77,7 @@ See: ### Automation -Converting a manual [Process](../risks/Process-Risk) into an automatic, computer-controlled one. +Converting a manual [Process](../risks/Process-Risk) into an automatic, machine-controlled one. See: diff --git a/docs/practices/development/Automating.md b/docs/practices/development/Automating.md deleted file mode 100644 index b846d4111..000000000 --- a/docs/practices/development/Automating.md +++ /dev/null @@ -1,14 +0,0 @@ - -### Automating - -One of the key ways to measure whether your team is doing _useful work_ is to look at whether, in fact, it can be automated. And this is the spirit of [DevOps](DevOps) - the idea that people in general are poor at repeatable tasks, and anything people do repeatedly _should_ be automated. - -Repetitive work of any kind is a [Process Risk](../risks/Process-Risk.md), and can be mitigated at the expense of attendant [Complexity Risk](../risks/Complexity-Risk.md) and [Schedule Risk](../risks/Scarcity-Risk.md#schedule-risk). - -Since this is a trade-off, you have to be careful about how you _weigh_ the [Process Risk](../risks/Process-Risk.md): clearly, it exists _into the future_. - -You are making a bet that acting now will pay off in decreased [Process Risk](../risks/Process-Risk.md) over the lifetime of the project. This is a hard thing to judge: - - How much [Process Risk](../risks/Process-Risk.md) are we carrying, week-to-week? (A good way to answer this is to look at past failures). - - How much [Complexity Risk](../risks/Complexity-Risk.md) will we pick up? - - How much [Schedule Risk](../risks/Scarcity-Risk.md#schedule-risk) (in spent developer effort) will we pick up? - - How long will the mitigation last before the process changes again? \ No newline at end of file diff --git a/docs/practices/development/Automation.md b/docs/practices/development/Automation.md new file mode 100644 index 000000000..240f7a3a2 --- /dev/null +++ b/docs/practices/development/Automation.md @@ -0,0 +1,41 @@ +--- +title: Automation +tags: + - Automation +practice: + aka: + - "Mechanisation" + - "Formalisation" + mitigates: + - tag: Implementation Risk + reason: "Reduces the variability in process completion" + - tag: Operational Risk + reason: "Introduces more consistency in process operations and removes opportunity for human error" + attendant: + - tag: Codebase Risk + reason: "More code means more software to manage" + - tag: Complexity Risk + reason: "Introducing code adds to the complexity of a project" + - tag: Feature Fit Risk + reason: "The automated process might not capture the variability of requirements of the original approach" + - tag: Invisibility Risk + reason: "The quality and performance characteristics may be obscured by automation." + - tag: Process Risk + reason: "Automation introduces a process" + related: + - /practices/development/Coding + - /practices/testing/Measurement +--- + + + +## Description + +> "Automation describes a wide range of technologies that reduce human intervention in processes, mainly by predetermining decision criteria, subprocess relationships, and related actions, as well as embodying those predeterminations in machines.": - [Automation, _Wikipedia_](https://en.wikipedia.org/wiki/Automation) + +One of the key ways to measure whether your team is doing _useful work_ is to look at whether, in fact, it can be automated. And this is the spirit of [DevOps](DevOps) - the idea that people in general are poor at repeatable tasks, and anything people do repeatedly _should_ be automated. + + +## See Also + + \ No newline at end of file diff --git a/docs/practices/development/Coding.md b/docs/practices/development/Coding.md index 05254ba93..ae9f64ceb 100644 --- a/docs/practices/development/Coding.md +++ b/docs/practices/development/Coding.md @@ -1,24 +1,27 @@ --- title: Coding +tags: + - Coding practice: aka: - "Software Development" - "Computer Programming" mitigates: - - page: tags/Feature-Risk + - tag: Feature Risk reason: "Build or improve some features which our clients will find useful." attendant: - - page: tags/Codebase-Risk + - tag: Codebase Risk reason: "More code means more software to manage" - - page: tags/Complexity-Risk + - tag: Complexity Risk reason: "Introducing code adds to the complexity of a project" - - page: tags/Implementation-Risk + - tag: Implementation Risk reason: Adding working code also introduces bugs. related: - - /practices/Refactoring - - /practices/Automating - - /practices/Outsourcing - - /practices/Pair-Programming + - /practices/development/Refactoring + - /practices/development/Automating + - /practices/coordination/Outsourcing + - /practices/development/Pair-Programming + - /practices/testing/testing --- diff --git a/docs/practices/development/Development.md b/docs/practices/development/Development.md deleted file mode 100644 index 9b4272826..000000000 --- a/docs/practices/development/Development.md +++ /dev/null @@ -1 +0,0 @@ -![Draft](/img/state/draft.png) diff --git a/docs/practices/development/Pair-Programming.md b/docs/practices/development/Pair-Programming.md index 7aa892e9f..be35b7803 100644 --- a/docs/practices/development/Pair-Programming.md +++ b/docs/practices/development/Pair-Programming.md @@ -1,25 +1,47 @@ +--- +title: Pair Programming +tags: + - Pair Programming +practice: + aka: + - "Mob Programming" + - "Pairing" + mitigates: + - tag: Staff Risk + reason: "Knowledge is shared across staff, reducing key person risk." + - tag: Agency Risk + reason: "Colleagues working together are able to keep each other honest." + - tag: Learning Curve Risk + reason: "Prototypes are a way of learning about a particular solution to a problem." + - tag: Communication Risk + reason: "A prototype often allows for communicating a design or idea in a way that a written document or diagram wouldn't." + - tag: Implementation Risk + reason: "More eyeballs means fewer bugs and a better implementation" + attendant: + - tag: Schedule Risk + reason: "Staff working together introduces redundancy which might slow down delivery speed." + - tag: Agency Risk + reason: "Staff might not like working in this arrangement." + related: + - /practices/Coding + - /practices/coordination/Review +--- + + +## Description -### Pair Programming / Mob Programming - -In the main, [Review](Review.md)) is the main way to mitigate [Coordination Risk](../risks/Coordination-Risk.md). For example: - - [Code Reviews](Review.md) - - [Stand Up Meetings](Review.md) - - [Presentations & Demos](Review.md) - - [Training](Review.md) +> "Pair programming is a software development technique in which two programmers work together at one workstation. One, the driver, writes code while the other, the observer or navigator,[1] reviews each line of code as it is typed in. The two programmers switch roles frequently." - [Pair Programming, _Wikipedia_](https://en.wikipedia.org/wiki/Pair_programming) -**Pair Programming** however _combines_ the review with the process of coding: there are now two heads at each terminal. What does this achieve? +**Pair Programming** combines the [review](../coordination/Review.md) with [coding](Coding.md): there are now two heads at each terminal. + - Clearly, we mitigate [Key-Man Risk](../risks/Coordination-Risk.md) as we've got two people doing every job. - Knowledge is transferred at the same time, too, mitigating [Specialist Risk](../risks/Coordination-Risk.md). - Proponents also argue that this mitigates [Complexity Risk](../risks/Complexity-Risk.md), as the software will be better quality. - Since the pair spend _so much time together_, the communication is very _high bandwidth_, so this mitigates [Communication Risk](../risks/Communication-Risk.md) - -But, conversely, there is a cost to **Pair Programming**: - - Having two people doing the job _one person could do_ intimates [Schedule Risk](../risks/Scarcity-Risk.md#schedule-risk). - - Could the same [Complexity Risk](../risks/Complexity-Risk.md) be mitigated just with more regular [Code Reviews](Review.md)? - - Sometimes, asking members of a team to work so closely together is a recipe for disaster. [Team Risk](../risks/Coordination-Risk.md) - - Not every pair programmer "shares" the keyboard time evenly, especially if ability levels aren't the same. - - There is only one **Feedback loop**, so despite the fact you have two people, you can only [Meet Reality](../thinking/Meeting-Reality.md) serially. - **Mob Programming** goes one stage further and suggests that we can write better software with _even more people around the keyboard_. So, what's the right number? Clearly, the usual trade-off applies: are you _mitigating_ more risk than you're _gaining_? - \ No newline at end of file +**Mob Programming** goes one stage further and suggests that we can write better software with _even more people around the keyboard_. So, what's the right number? Clearly, the usual trade-off applies: are you _mitigating_ more risk than you're _gaining_? + +## See Also + + \ No newline at end of file diff --git a/docs/practices/development/Prototyping.md b/docs/practices/development/Prototyping.md index 94f3c6be3..222a090ba 100644 --- a/docs/practices/development/Prototyping.md +++ b/docs/practices/development/Prototyping.md @@ -1,20 +1,22 @@ --- title: Prototyping +tags: + - Prototyping practice: aka: - "Spike Solution" - "Proof of Concept (POC)" mitigates: - - page: tags/Complexity-Risk + - tag: Complexity Risk reason: "Prototyping allows you to explore an idea or design without committing to it. If the design turns out to be over-complex, it can be avoided." - - page: tags/Schedule-Risk + - tag: Schedule Risk reason: "Prototyping aims to produce quick working examples to help understand a concept." - - page: tags/Learning-Curve-Risk + - tag: Learning Curve Risk reason: "Prototypes are a way of learning about a particular solution to a problem." - - page: tags/Communication-Risk + - tag: Communication Risk reason: "A prototype often allows for communicating a design or idea in a way that a written document or diagram wouldn't." attendant: - - page: tags/Complexity-Risk + - tag: Complexity Risk reason: "Prototypes that turn into the chosen solution often take shortcuts in design that are not rectified." related: - /practices/MVP diff --git a/docs/practices/development/Refactoring.md b/docs/practices/development/Refactoring.md index 365428fca..79540b90d 100644 --- a/docs/practices/development/Refactoring.md +++ b/docs/practices/development/Refactoring.md @@ -1,8 +1,33 @@ - -### Refactoring +--- +title: Refactoring +tags: + - Refactoring +practice: + aka: + - "Factoring" + - "Separation of Concerns" + mitigates: + - tag: Complexity Risk + reason: "Refactoring is aimed at making code more orthogonal, less duplicative and clearer to understand" + - tag: Communication Risk + reason: "Well-factored code should be easier to understand." + attendant: + - tag: Schedule Risk + reason: "Refactoring in large chunks can take significant time to complete." + - tag: Feature Regression Risk + reason: "Done carelessly, refactoring can introduce new issues into the codebase" + related: + - /practices/Coding +--- + + + +## Description The term "refactoring" probably stems from the mathematical concept of _(Factorization)[https://en.wikipedia.org/wiki/Factorization]_. Factorizing _polynomial equations_ or _numbers_ means to identify and make clear their distinct components. +> "In computer programming and software design, code refactoring is the process of restructuring existing computer code—changing the factoring—without changing its external behavior." - [Refactoring, _Wikipedia_](https://en.wikipedia.org/wiki/Code_refactoring) + tbd: SoC Most coders use the phrase "refactoring", and intuitively understand what it is. It shouldn't have been hard to find a clear explanation for this page, but sadly it was. There are some very woolly definitions of "refactoring" around, such as: @@ -18,4 +43,15 @@ On **Refactoring**, Kent Beck says: > "If a programmer sees a one-minute ugly way to get a test working and a ten-minute way to get it working with a simpler design, the correct choice is to spend the ten minutes. " -- Kent Beck, _Extreme Programming Explained_ -This is a bold, not-necessarily-true assertion. How does that ratio stack up when applied to _hours_ or _days_? But you can see how it's motivated: Kent is saying that the nine extra minutes of [Schedule Risk](../risks/Scarcity-Risk.md#schedule-risk) are _nothing_ compared to the carry cost of [Complexity Risk](../risks/Complexity-Risk.md) on the project. \ No newline at end of file +This is a bold, not-necessarily-true assertion. How does that ratio stack up when applied to _hours_ or _days_? But you can see how it's motivated: Kent is saying that the nine extra minutes of [Schedule Risk](../risks/Scarcity-Risk.md#schedule-risk) are _nothing_ compared to the carry cost of [Complexity Risk](../risks/Complexity-Risk.md) on the project. + +## External References + +- [Separation of Concerns](https://en.wikipedia.org/wiki/Separation_of_concerns) Wikipedia Page. +- [Refactoring](https://martinfowler.com/books/refactoring.html) Book by Martin Fowler. + + +## See Also + + + diff --git a/docs/practices/service/Tool-Adoption.md b/docs/practices/development/Tool-Adoption.md similarity index 100% rename from docs/practices/service/Tool-Adoption.md rename to docs/practices/development/Tool-Adoption.md diff --git a/docs/practices/testing/Measurement.md b/docs/practices/testing/Measurement.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/risks/Complexity-Risk.md b/docs/risks/Complexity-Risk.md index f5381504e..ea0f384d4 100644 --- a/docs/risks/Complexity-Risk.md +++ b/docs/risks/Complexity-Risk.md @@ -13,6 +13,7 @@ tags: - Dead-End Risk - Codebase Risk - Risks + - Refactoring redirect_from: - /Complexity-Risk --- diff --git a/src/theme/PracticeIntro/index.js b/src/theme/PracticeIntro/index.js index e7297a3be..c7309b9b9 100644 --- a/src/theme/PracticeIntro/index.js +++ b/src/theme/PracticeIntro/index.js @@ -6,10 +6,13 @@ function formatReadableTag(page) { return page.replaceAll("-", " ").substring(page.lastIndexOf("/")+1) } -const Risk = ({page, reason}) => { - const title = formatReadableTag(page) +function tagUrl(tag) { + return "/tags/"+tag.replaceAll(" ", "-") +} + +const Risk = ({tag, reason}) => { return ( -
  • {title}: {reason}
    • +
  • {tag}: {reason}
    • ) } @@ -31,13 +34,13 @@ export default ({details}) => {

    Addresses / Mitigates

      { - details.mitigates.map(i => ) + details.mitigates.map(i => ) }

    Attendant Risks

      { - details.attendant.map(i => ) + details.attendant.map(i => ) }