From 181835021b5a27c5f2faaf0bcb0992d175e6b136 Mon Sep 17 00:00:00 2001 From: David Wilding Date: Tue, 10 Feb 2026 13:10:19 +0800 Subject: [PATCH 1/3] reorganise headings --- docs/designing-framework.rst | 41 ++++++++++++++++++++---------------- 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/docs/designing-framework.rst b/docs/designing-framework.rst index 2733f02..aabd70c 100644 --- a/docs/designing-framework.rst +++ b/docs/designing-framework.rst @@ -7,8 +7,8 @@ All the settings for implementing and configuring the components of the framewor For example, objectives can be found at *Admin* > *Framework* > *Objectives*. -Objectives -========== +The essentials of your framework +================================ At the heart of the framework are the **objectives** you're working towards. An objective is a particular dimension of quality in your field. (For example, if you want to use the framework to drive up engineering standards, one of the dimensions of quality you focus on might be *automated testing*.) @@ -37,6 +37,10 @@ Here's a part of quality framework, with just two objectives described, for *Inc - Automated spelling checks are part of the CI pipeline. +Defining your framework +======================= + + Working incrementally --------------------- @@ -47,11 +51,8 @@ The risk is that people (and you are probably one of them) love to create framew While designing your framework, you will often need to hush your inner rationalist so that your inner pragmatist can be heard. -Defining the framework ----------------------- - -Objectives -~~~~~~~~~~ +Defining objectives +------------------- Consider a dimension of quality in your field, an aspect that you care about - like *Inclusive language* or *Automated spelling checks* @@ -62,8 +63,8 @@ For example, if your framework is concerned with engineering standards, "automat This is especially important for the first objectives that start appearing in your scheme. Later objectives can afford to be more abstruse or represent value that needs some explanation, as long as you have already set out ones that are readily accepted, that people are able to buy into without effort. -Conditions and levels -~~~~~~~~~~~~~~~~~~~~~ +Defining conditions and levels +------------------------------ For each objective, you need to write out some conditions representing measurable, checkable states of affairs that you want to become the case. @@ -86,8 +87,8 @@ By the time you have a few, you will probably see ways of grouping them accordin * There is 100% test coverage. -Making it work well -------------------- +Making your framework work well +=============================== What makes our "automated testing" objective a good example? Let's have a look at the conditions. They're arranged in three levels: from *Started* via *First results* to *Mature*. It's a reasonable set of levels, and arguably a good default to reach for. @@ -95,7 +96,7 @@ There's an art to defining conditions that represent the progress you want. Reme Securing acceptance -~~~~~~~~~~~~~~~~~~~ +------------------- An effective strategy is to use the first group of conditions not so much to achieve results, but to secure acceptance. @@ -111,7 +112,7 @@ These *Started* objectives are easy for a team to accept. They don't actually co Qualitative conditions -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- In *First results*, there is a concrete demand: *a significant increase in test coverage*. It *doesn't* say (for example) "at least 50%". @@ -139,7 +140,7 @@ In "There is 100% test coverage" 100% isn't just a number: it's completion. But, Progression -~~~~~~~~~~~ +----------- The conditions in the three levels represent getting in motion, achieving results, and completion. It's a good progression, but it's not the only good one. @@ -154,6 +155,10 @@ Be imaginative and pragmatic. The important thing in any case is that each succe And don't make anything more complicated than it needs to be. It can be perfectly effective for a particular objective to have a small handful of conditions, all listed under the sole level *Done*. +More components +=============== + + Objective groups ---------------- @@ -163,7 +168,7 @@ It's partly a matter of convenience, but categorising things also has a useful f Unstarted reasons -================= +----------------- If an objective hasn't attained one of the defined levels, then it is *unstarted*. There are different reasons why an objective might be unstarted. A reasonable default set is: @@ -176,7 +181,7 @@ If an objective hasn't attained one of the defined levels, then it is *unstarted Project agreement statuses -========================== +-------------------------- A sensible default set: @@ -186,7 +191,7 @@ A sensible default set: Project review statuses -======================= +----------------------- In the review phase, each project's *Review status* should be set. @@ -199,7 +204,7 @@ A suggested set of statuses: Numerical values -================ +---------------- In order to derive numerical metrics from the framework, that make it easier to get an at-a-glance sense of progress or to see gaps in it, many of the things described above can be associated with a value. From aca0e9bc5bbdcd5b7ff6901e1ba01eecef6c98a4 Mon Sep 17 00:00:00 2001 From: David Wilding Date: Tue, 10 Feb 2026 13:10:40 +0800 Subject: [PATCH 2/3] tidy title syntax --- docs/designing-framework.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/designing-framework.rst b/docs/designing-framework.rst index aabd70c..a0e1320 100644 --- a/docs/designing-framework.rst +++ b/docs/designing-framework.rst @@ -1,6 +1,6 @@ -=================================== +============================= Designing a quality framework -=================================== +============================= All the settings for implementing and configuring the components of the framework described here are in the application's admin - *Admin* > *Framework*. From dd61bc7b10eef965b3e27c475aa28e02f5cc9836 Mon Sep 17 00:00:00 2001 From: David Wilding Date: Tue, 10 Feb 2026 13:10:59 +0800 Subject: [PATCH 3/3] add missing full stop --- docs/designing-framework.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designing-framework.rst b/docs/designing-framework.rst index a0e1320..c3785e6 100644 --- a/docs/designing-framework.rst +++ b/docs/designing-framework.rst @@ -54,7 +54,7 @@ While designing your framework, you will often need to hush your inner rationali Defining objectives ------------------- -Consider a dimension of quality in your field, an aspect that you care about - like *Inclusive language* or *Automated spelling checks* +Consider a dimension of quality in your field, an aspect that you care about - like *Inclusive language* or *Automated spelling checks*. Whatever it is, it should be something meaningful and recognisable to the people that you expect to work with the framework.