Soliciting feedback on a boilerplate template for a POLITICS file for free software projects
cc: @Shamar
https://discourse.qoto.org/t/boilerplate-template-for-politics-md/87?u=jump_spider
Since this isn't nearly as established a convention as some other forms of repo boilerplate, you probably want to briefly describe when I must read this document. For example, I should read a Code of Conduct before interacting with others in your project space, the licence before distributing your code, etc.
I got through your introductory paragraph and thought, "Why do your politics matter to me?" As a user I care about how the software helps me reach my goals, not yours.
@khird @Shamar
Good point re: why it should matter to anyone else. I posted this in the Discourse thread, but how does this read?
# Description of this document
The creation and distribution of software do not exist in a vacuum. As such, this document outlines specific and quantifiable political goals for this project. This file is a living document and is expected and encouraged to change over time; changes will be included in the CHANGELOG, though are not suggested to trigger a version bump if using semantic versioning.
## Social goals of react-useintersection
The `IntersectionObserver` api is a powerful JavaScript construct. The author of this package intends for it to help facilitate:
1. **Accessible UX design:** Programmatically determing the intersection of nodes with the screen gives powerful flexibility to control styling and layout.
2. **Wider understanding of advanced JavaScript apis by helping them be more easily used in the React framework:** The `IntersectionObserver` api is but one of several Observer apis in JavaScript, most of which are in the author's opinion relatively unknown to the average programmer because there is a lack of high level packages for them in frameworks such as React.
It's quite a bit clearer now! Cutting out the snarky jabs at people who "pretend technology exists or has ever existed separate from the natural tendency for human agents to consolidate power" and "[mere] vague principles that corporate entities routinely ignore" has helped a lot. You could probably go even further with this, cutting everything before "This document outlines...".
On the other hand, I still don't understand the target audience. It would be nice if fairly early on you say, "This document is required reading for contributors; users can skip it," or whatever is appropriate to your vision for who reads it.
@khird
Well, as @ Shamar clarified, users benefit from reading to understand what the current intent of the project is. For instance, I've been thinking about starting a toy project for Elm, involving generating a yaml for installing and configuring arbitrary tools, but I'm going to limit the scope to asdf and n for language managers. That will be something I include in POLITICS.txt, so users can know upfront that I don't currently intend to support rvm, for example