[pull] main from dwmkerr:main

.github/contributing.md

@@ -3,12 +3,14 @@
 <!-- vim-markdown-toc GFM -->
 
 - [Goal of the Project](#goal-of-the-project)
+- [Editorial Process](#editorial-process)
 - [Example Law: The Law of Leaky Abstractions](#example-law-the-law-of-leaky-abstractions)
 - [Translations](#translations)
 - [How do I know if a law is relevant?](#how-do-i-know-if-a-law-is-relevant)
 - [How do I know if a law is 'well known' enough?](#how-do-i-know-if-a-law-is-well-known-enough)
 - [Use of Images](#use-of-images)
 - [Developer Guide](#developer-guide)
+- [Contributor Credit and a Possible Book](#contributor-credit-and-a-possible-book)
 
 <!-- vim-markdown-toc -->
 
@@ -33,12 +35,23 @@ Some other tips:
 - Do not advocate for the law, or aim to be opinionated on the correctness or incorrectness of the law, as this repository is simply the descriptions and links.
 - Avoid 'you' when writing. For example, prefer "This law suggests refactoring should be avoided when..." rather than "you should avoid refactoring when...". This keeps the style slightly more formal and avoids seeming like advocation of a law.
 
-An example law is shown below, which covers most of the key points:
+## Editorial Process
+
+Every contribution is edited, either before it is merged or shortly afterwards. In practice this means changes to style, tone, structure and length, a check that the description is correct and relevant, and a check that quotes and images are properly attributed.
+
+A law may therefore end up reading quite differently from the version that was submitted. This is not a comment on the quality of the contribution. The aim is to keep a long document in a single voice, and to keep every entry to the same shape and length.
+
+Two things make this much easier:
+
+- Do not copy and paste text from other sources, unless it is explicitly quoted and attributed. See [Use of Images](#use-of-images) for the equivalent point about pictures.
+- Include a link to the source for anything you reference, and the licence for any image.
 
 ---
 
 ## Example Law: The Law of Leaky Abstractions
 
+An example law is shown below, which covers most of the key points.
+
 [The Law of Leaky Abstractions on Joel on Software](https://www.joelonsoftware.com/2002/11/11/the-law-of-leaky-abstractions/)
 
 > All non-trivial abstractions, to some degree, are leaky.
@@ -87,19 +100,30 @@ A good test is 'If I search for it on Google, will I find it in the first few re
 
 ## Use of Images
 
-Please make sure to attribute images properly if you are referencing them. Also, include a white background, as some viewers will be viewing the site in 'Dark Mode' which can make images with a transparent background difficult to read.
+Original diagrams are strongly preferred. If you do reference an image from elsewhere, please include the source URL, the author and the licence in the pull request, so that it can be attributed properly. Images without a clear licence cannot be accepted, and images may later be redrawn to keep the artwork consistent.
+
+Also include a white background, as some viewers will be reading in 'Dark Mode', which can make images with a transparent background difficult to read.
 
 ## Developer Guide
 
 Where possible, anything which is not the core `README.md` file is kept in the `.github/` folder to keep the landing page for the repository as clean as possible.
 
-To use the makefile, pass its path explicitly, e.g:
+The website at [hacker-laws.com](https://hacker-laws.com) is built from `README.md`. To build and serve it locally:
 
 ```bash
-make -f .github/makefile
+cd .github/website
+make install
+make serve
 ```
 
-Or create an alias:
+Run `make` on its own to see the other targets.
 
-```bash
-alias hlmake="make -f .github/makefile"
+## Contributor Credit and a Possible Book
+
+This project may in time be turned into a book.
+
+If that happens, every contributor will be credited in an appendix. Contributors are listed by GitHub handle by default. If you would prefer to be credited by name, please say so in your pull request.
+
+By opening a pull request you grant the maintainer a permanent, worldwide, royalty-free and non-exclusive licence to use, edit, translate and publish your contribution in any format, including print and electronic editions which are sold. You keep the copyright in what you wrote, and remain free to use it elsewhere yourself.
+
+The repository stays under [CC BY-SA 4.0](../LICENSE) and will remain free to read.

.github/workflows/cicd.yaml

@@ -41,47 +41,6 @@ jobs:
           manifest-file: .github/release-please-manifest.json
           config-file: .github/release-please-config.json
 
-  release-pdf:
-    runs-on: ubuntu-24.04
-    needs: release
-    if: ${{ needs.release.outputs.released }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      # Set a descriptive version. For PRs it'll be the short sha.
-      - name: Check Version
-        run: echo "${VERSION}"
-        env:
-          VERSION: ${{ needs.release.outputs.tag }}
-
-      # Set a descriptive version. For PRs it'll be the short sha.
-      - name: Prepare Markdown
-        run: |
-          # Set the env vars we use (version set for clarity).
-          export DATE=$(date +%F)
-          export VERSION="${VERSION}"
-          make -f .github/makefile prepare-markdown
-        env:
-          VERSION: ${{ needs.release.outputs.tag }}
-
-      # Create the PDF files.
-      - name: Create PDF
-        run: make -f .github/makefile create-pdf
-
-      # Publish the PDF and intermediate markdown as an artifact.
-      # - name: Publish PDF Artifact
-      #   uses: actions/upload-artifact@3
-      #   with:
-      #     name: hacker-laws.pdf
-      #     path: hacker-laws.pdf
-
-      - name: Attach assets to GitHub Release
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          gh release upload "${{ needs.release.outputs.tag }}" --clobber hacker-laws.pdf hacker-laws.md
-
   deploy:
     environment:
       name: github-pages

.gitignore

@@ -1 +1,2 @@
 .DS_Store
+scratch/

README.md

@@ -8,7 +8,6 @@
 - 🧠 Check out my new project [Terminal AI](https://github.com/dwmkerr/terminal-ai)
 - ☕️ Like this project? Consider [buying me a coffee with a one-off donation](https://github.com/sponsors/dwmkerr?frequency=one-time)
 - 🎧 Listen to the podcast [The Changelog - Laws for Hackers to Live By](https://changelog.com/podcast/403)
-- 📖 Download the [PDF eBook](https://github.com/dwmkerr/hacker-laws/releases/latest/download/hacker-laws.pdf)
 - 🌏 See the Translations: [🇧🇷](./translations/pt-BR.md) [🇨🇳](https://github.com/nusr/hacker-laws-zh) [🇫🇷](./translations/fr.md) [🇮🇹](./translations/it-IT.md) [🇱🇻](./translations/lv.md) [🇰🇷](https://github.com/codeanddonuts/hacker-laws-kr) [🇷🇺](https://github.com/solarrust/hacker-laws) [🇪🇸](./translations/es-ES.md) [🇹🇷](./translations/tr.md) [🇮🇩](./translations/id.md) [🇯🇵](./translations/jp.md) [🇵🇱](./translations/pl.md) [🇻🇳](./translations/vi.md)
 
 ---
@@ -88,7 +87,6 @@
     - [The Principle of Least Astonishment](#the-principle-of-least-astonishment)
 - [Reading List](#reading-list)
 - [Online Resources](#online-resources)
-- [PDF eBook](#pdf-ebook)
 - [Podcast](#podcast)
 - [Contributors](#contributors)
 
@@ -98,6 +96,8 @@
 
 There are lots of laws which people discuss when talking about development. This repository is a reference and overview of some of the most common ones. Please share and submit PRs!
 
+This project may in time be turned into a book. If it is, all contributors will be credited in an appendix, listed by GitHub handle, or by name if requested in the pull request. See the [Contributing Guidelines](.github/contributing.md) for details.
+
 Warning: This repo contains an explanation of some laws, principles and patterns, but does not _advocate_ for any of them. Whether they should be applied will always be a matter of debate, and greatly dependent on what you are working on.
 
 ## Laws
@@ -141,7 +141,7 @@ Best illustrated with an example. If a program is made up of two parts, part A,
 
 The diagram below shows some examples of potential improvements in speed:
 
-<img width="480px" alt="Diagram: Amdahl's Law" src="./images/amdahls_law.png" />
+<img width="560px" alt="Diagram: Amdahl's Law, showing speedup against the number of processors for four different parallel portions" src="./images/amdahls-law.svg" />
 
 
 As can be seen, even a program which is 50% parallelisable will benefit very little beyond 10 processing units, whereas a program which is 95% parallelisable can still achieve significant speed improvements with over a thousand processing units.
@@ -283,7 +283,7 @@ Real-world examples:
 
 Fitts' law predicts that the time required to move to a target area is a function of the distance to the target divided by the width of the target.
 
-<img width="300px" alt="Diagram: Fitts Law" src="./images/Fitts_Law.svg" />
+<img width="420px" alt="Diagram: Fitts' Law, showing the distance D to a target and the width W of that target" src="./images/fitts-law.svg" />
 
 
 The consequences of this law dictate that when designing UX or UI, interactive elements should be as large as possible and the distance between the users attention area and interactive element should be as small as possible. This has consequences on design, such as grouping tasks that are commonly used with one another close.
@@ -354,7 +354,7 @@ This principle suggests that actions resulting in a negative outcome were not a
 
 In the equation below, `T` is the time to make a decision, `n` is the number of options, and `b` is a constant which is determined by analysis of the data.
 
-![Hicks law](./images/hicks_law.svg)
+<img width="240px" alt="Equation: T equals b multiplied by the base two logarithm of n plus one" src="./images/hicks-law.svg" />
 
 
 This law only applies when the number of options is _ordered_, for example, alphabetically. This is implied in the base two logarithm - which implies the decision maker is essentially performing a _binary search_. If the options are not well ordered, experiments show the time taken is linear.
@@ -404,7 +404,7 @@ For example, a decrease in response latency for a particular end-point could cau
 
 The Hype Cycle is a visual representation of the excitement and development of technology over time, originally produced by Gartner. It is best shown with a visual:
 
-![The Hype Cycle](./images/gartner_hype_cycle.png)
+<img width="800px" alt="Diagram: The Hype Cycle, showing expectations over time through the technology trigger, peak of inflated expectations, trough of disillusionment, slope of enlightenment and plateau of productivity" src="./images/hype-cycle.svg" />
 
 
 In short, this cycle suggests that there is typically a burst of excitement around new technology and its potential impact. Teams often jump into these technologies quickly, and sometimes find themselves disappointed with the results. This might be because the technology is not yet mature enough, or real-world applications are not yet fully realised. After a certain amount of time, the capabilities of the technology increase and practical opportunities to use it increase, and teams can finally become productive. Roy Amara's quote sums this up most succinctly - "We tend to overestimate the effect of a technology in the short run and underestimate in the long run".
@@ -805,7 +805,7 @@ This rule suggests that regardless of the size of the company, teams should be s
 
 The number of links between people can be expressed as `n(n-1)/2` where n = number of people.
 
-<img width="200px" alt="Complete graph; Links between people" src="./images/complete_graph.png" />
+<img width="220px" alt="Diagram: a complete graph of seven nodes, showing a link between every pair of people" src="./images/complete-graph.svg" />
 
 ### Twyman's law
 
@@ -1216,12 +1216,6 @@ Some useful resources and reading.
 
 - [CB Insights: 8 Laws Driving Success In Tech: Amazon's 2-Pizza Rule, The 80/20 Principle, & More](https://www.cbinsights.com/research/report/tech-laws-success-failure) - an interesting write up of some laws which have been highly influential in technology.
 
-## PDF eBook
-
-The project is available as a PDF eBook, [download the latest PDF eBook with this link](https://github.com/dwmkerr/hacker-laws/releases/latest/download/hacker-laws.pdf) or check the [release](https://github.com/dwmkerr/hacker-laws/releases) page for older versions.
-
-A new version of the eBook is created automatically when a new version tag is pushed.
-
 ## Podcast
 
 Hacker Laws has been featured in [The Changelog](https://changelog.com/podcast/403), you can check out the Podcast episode with the link below: