Linked & described some telemetry data

.pre-commit-config.yaml

@@ -6,6 +6,7 @@ repos:
     rev: cef0300fd0fc4d2a87a85fa2093c6b283ea36f4b # frozen: v5.0.0
     hooks:
     -   id: trailing-whitespace
+        args : [ --markdown-linebreak-ext=md ]
     -   id: end-of-file-fixer
     -   id: check-yaml
     -   id: check-added-large-files

README.md

@@ -1,14 +1,17 @@
-![A heart rate monitor with the FreeCAD logo on it](Resources/icons/TelemetryIcon.png "Telemetry Addon")
+![Logo]
 
-# FreeCAD Telemetry Addon
+# Telemetry Addon [ Beta ]
 
-This optional addon sends selected FreeCAD installation and settings information to a centralized database. It is still
-in the beta release stage, but you are welcome to test it out. See [Installing Telemetry](#installing-telemetry) below.
+Sends non-identifying usage information to FreeCAD.
 
-# Why you should share telemetry with the FreeCAD project
+This addon doesn't ship with FreeCAD and is optional.
 
-[FreeCAD](https://freecad.org) is a community project. We freely contribute our time and money to make the software as
-good as possible for the largest number of users. Contributing data is another way of supporting the project.
+*If you have the time, please try out this Beta!*  
+*See [Installing Telemetry](#installation) below.*
+
+## Why you should share telemetry with the FreeCAD project
+
+[FreeCAD] is a community project. We freely contribute our time and money to make the software as good as possible for the largest number of users. Contributing data is another way of supporting the project.
 
 Sharing telemetry with FreeCAD helps the project leaders and developers make a better solution for everyone and allocate
 donations responsibly. Without good data, it is difficult to make good decisions between competing priorities: for
@@ -32,7 +35,7 @@ The telemetry also helps us fine tune the user experience to benefit the largest
 These are just examples, and it is important to understand that we will never sell data to third parties and will not
 use the data to market products or services to you.
 
-# What data is sent?
+## Shared Data
 
 Telemetry data is selected to be non-identifying. Nothing sent is personally identifying: upon installation of the
 Addon you are automatically assigned a random UUID that can be used to request data removal if you later choose
@@ -45,73 +48,87 @@ of FreeCAD.
 
 In addition, three other categories of information are usually sent, but can be disabled on a per-category basis.
 
-## Addons list
+### Addons
+
+We may collect the list of names of your installed addons.
+
+This list can be obtained by listing the  contents of the  
+`{UserAppDataDir}/Mod` directory on your system.
+
+### Preferences
+
+We may collect a variety of your preferences:
 
-A list of all installed addons, obtained by listing the contents of the `{UserAppDataDir}/Mod` directory on your
-system.
+-   Language
+-   Theme
+-   Stylesheet
+-   Window geometry
+-   Overlay stylesheet
+-   Default unit schema
 
-## FreeCAD preferences
+### System
 
-The following FreeCAD preferences:
+We may collect system details from the  
+output of the following Python commands:
 
-* Language
-* Theme
-* Stylesheet
-* Window geometry
-* Overlay stylesheet
-* Default unit schema
+-   [`platform.machine()`][Python - Machine]  
+    ➞ `x86_64`
 
-## System statistics
+-   [`platform.system()`][Python - System]  
+    ➞ `Linux`
 
-The output of the following Python commands:
+-   [`platform.version()`][Python - SVersion]  
+    ➞ `#45-Ubuntu SMP PREEMPT_DYNAMIC Thu Dec 06 12:50:01 UTC 2024`
 
-* `platform.machine()`
-* `platform.system()`
-* `platform.version()`
-* `platform.python_version()`
-* `FreeCADGui.getMainWindow().screen().availableSize()`
-* `FreeCADGui.getMainWindow().screen().devicePixelRatio()`
+-   [`platform.python_version()`][Python - PVersion]  
+    ➞ `3.12.1`
 
-## Future plans
+-   [`FreeCADGui.getMainWindow().screen().availableSize()`][QT - Size]  
+    ➞ `{ width : 1920 , height : 1080 }`
+
+-   [`FreeCADGui.getMainWindow().screen().devicePixelRatio()`][QT - Ratio]  
+    ➞ `1.0`
+
+### Future plans
 
 Eventually if FreeCAD crashes while this addon is running, crash data will automatically be sent to the server.
 This data **will not** include information about your CAD model or detailed information about your system. No
 data will be added to the collection list without a dialog informing you of the change when the new version
 is first launched.
 
-## Disabling collection
+### Disabling collection
 
 You can disable this data reporting by removing the Addon via the Addon Manager, by manually deleting the addon
 from your FreeCAD Mod directory, or temporarily by unchecking "Enabled" in the Telemetry Addon's preferences. You
 may also individually uncheck the categories described above if you are not comfortable sending the listed data, but
 still wish to participate in the overall metrics program.
 
-## Requesting removal of data
+### Data Removal
 
 To request that your data be removed from our telemetry collection, click the button in the Telemetry preferences
 page to engage an automated process, or send a removal request with your UUID (found in the FreeCAD Tools menu, under
 "Edit parameters" -- look for `BaseApp/Preferences/Mod/Telemetry/PostHogUUID`) to
 [[email protected]](mailto:[email protected]). This will not affect your use of FreeCAD in any way, nor cancel
 any other online accounts you may have: those accounts are not tied in any way to the generated UUID.
 
-## Requesting a copy of your data
+### Requesting a copy of your data
 
 To receive a copy of the data associated with your UUID, please send email to
 [[email protected]](mailto:[email protected]) with your UUID (see instructions in
 [Requesting removal of data](#requesting-removal-of-data)) and your preferred data format (CSV or XLSX).
 
-## Who has access to the data?
+### Who has access to the data?
 
 The data is collected by [The FreeCAD project association AISBL](https://fpa.freecad.org/) who stewards the data
 on behalf of all users and developers of FreeCAD. Only FPA officers, FreeCAD's maintainers, and system administrators
 have access to the raw data, but aggregate data will be made available to the public. Publication of the data is
 currently a work-in-progress.
 
-## Privacy and GDPR compliance
+### Privacy and GDPR compliance
 
 See our [Privacy Policy](PRIVACY_POLICY.md).
 
-# Installing Telemetry
+## Installation
 
 While it is still in beta testing this addon is not in the official FreeCAD addons list. The easiest way to install it
 is to edit the Addon Manager's preferences to add a new custom repository,
@@ -122,3 +139,15 @@ which the Addon Manager will handle.
 As an alternative you can install the addon manually by cloning it from its git repository into your
 `{userAppDataDir}/Mod` directory. Use pip to install the contents of the `requirements.txt` file (use the same Python
 interpreter that FreeCAD uses to ensure the requirements are found).
+
+
+[FreeCAD]: https://freecad.org
+[Logo]: Resources/icons/TelemetryIcon.png "A heart rate monitor with the FreeCAD logo on it"
+
+[Python - SVersion]: https://docs.python.org/3/library/platform.html#platform.version
+[Python - PVersion]: https://docs.python.org/3/library/platform.html#platform.python_version
+[Python - Machine]: https://docs.python.org/3/library/platform.html#platform.machine
+[Python - System]: https://docs.python.org/3/library/platform.html#platform.system
+
+[QT - Ratio]: https://doc.qt.io/qt-6/qscreen.html#devicePixelRatio-prop
+[QT - Size]: https://doc.qt.io/qt-6/qscreen.html#availableSize-prop