Merge pull request dwmkerr#477 from dwmkerr/docs/book-contributor-credit

docs: note editorial process, contributor credit and possible book

Author: dwmkerr

.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/makefile

@@ -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

.github/workflows/cicd.yaml

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

.gitignore

@@ -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
@@ -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: