Tidy up use of first person in docs. Since I don't run the only server, referring to "me" in the docs was ambiguous and probably reads oddly to the other server owners.

2026-09-28 18:22:05 +00:00 · 2026-09-27 16:47:30 +01:00
parent 5d8cd38351
commit 71557db37c
21 changed files with 112 additions and 90 deletions
@@ -34,20 +34,20 @@
        </li>
    </ol>
    <p>Spothole's web interface exists not just for the end user, but also as a reference implementation for the API, so
-        I have chosen to demonstrate both methods of filtering.</p>
+        it demonstrates both methods of filtering.</p>
    <h4 class="mt-4">How is this better than DXheat, DXsummit, POTA's own website, etc?</h4>
    <p>It's probably not? But it's nice to have choice.</p>
    <p>I think it's got three key advantages over those sites:</p>
    <ol>
        <li>It provides a public, <a href="/apidocs">well-documented API</a> with an <a href="/apidocs/openapi.yml">OpenAPI
            specification</a>. Other sites don't have official APIs or don't bother documenting them publicly, because
-            they want people to use their web page. I like Spothole's web page, but you don't have to use it&mdash;if
+            they want people to use their web page. Spothole has a nice web page too, but you don't have to use it&mdash;if
            you're a programmer, you can build your own software on Spothole's API. Spothole does the hard work of
            taking all the various data sources and providing a consistent, well-documented data set. You can then do
            the fun bit of writing your own application.
        </li>
-        <li>It grabs data from a lot more sources. I've seen other sites that pull in DX Cluster and POTA spots
-            together, but nothing on the scale of what Spothole supports.
+        <li>It grabs data from a lot more sources. Other sites pull in DX Cluster and spots from a few "on the air"
+            activities together, but nothing on the scale of what Spothole supports.
        </li>
        <li>Spothole is open source, so anyone can contribute the code to support a new data source or add new features,
            and share them with the community.
@@ -70,9 +70,9 @@
        waiting around three minutes to see a newly added spot, or 40 minutes to see a newly added alert.</p>
    <h4 class="mt-4">What licence does Spothole use?</h4>
    <p>Spothole's source code is licenced under the Public Domain. You can write a Spothole client, run your own server,
-        modify it however you like, you can claim you wrote it and charge people £1000 for a copy, I don't really mind.
-        (Please don't do the last one. But if you're using my code for something cool, it would be nice to hear from
-        you!)</p>
+        modify it however you like, you can claim you wrote it and charge people £1000 for a copy, it really doesn't
+        matter. (Please don't do the last one. But if you're using Spothole's code for something cool, its developer,
+        <a href="https://ianrenton.com">Ian, M0TRT</a>, would love to hear from you!)</p>
    <h4 class="mt-4">What commands are supported in the telnet server?</h4>
    <p>Currently, <code>exit</code>, and nothing else. Support for some DXSpider-like commands may be added to Spothole
        in due course, but at the moment if you want to add Spothole as a telnet cluster data source to your desktop
@@ -27,16 +27,20 @@
    like.</p>

 <h2 class="mt-4">Legal</h2>
-<p>This server is run by an amateur radio operator with callsign {{ server_owner_callsign }}. You should contact them if
-    you have any issues with the website.</p>
-<p>Spothole exists as an aggregator of data from many other sources. To the best of my knowledge, all these sources
-    either:</p>
+<p>This server is run by an amateur radio operator with callsign {{ server_owner_callsign }}. You should contact them
+    with any questions about privacy or legal matters relating to this server, or if you have any issues with the
+    website.</p>
+<p>Spothole exists as an aggregator of data from many other sources. To the best of the Spothole developers' knowledge,
+    all these sources either:</p>
 <ul>
    <li>State licence terms that make their data acceptable for use on a non-profit website like this one, or,</li>
-    <li>Require you to ask permission before using their data, which I have done, or,</li>
+    <li>Require you to ask permission before using their data, which has been done, or,</li>
    <li>Have an open API and are happy with third-party use.</li>
 </ul>
-<p>If you represent one of these data sources and would like it removed from Spothole, please let me know.</p>
+<p>If you represent one of these data sources and would like it removed, there are two options. The owner of this
+    server, {{ server_owner_callsign }}, can disable it on this server straight away. To have it removed from the
+    Spothole software itself, so that future versions of Spothole no longer support it on any server, please contact
+    Spothole's developer, <a href="https://ianrenton.com">Ian Renton, M0TRT</a>.</p>
 <p>Spothole does not produce any real data of its own. Information such as spots and alerts that Spothole displays are
    entered by users, often of other websites. The data may be the property of the user or the other website, depending
    on their terms and conditions.</p>
@@ -40,8 +40,8 @@
        Vestigios de España (DMVE), Diploma Estaciones de Ferrocarril de España (DEFE), Diploma Teatri Musei e Belle
        Arti (DTMBA), British Inland Waterways on the Air (BIWOTA), Castles on the Air (COTA), Polish Gmina Award (PGA),
        Diplôme des Moulins de France (DMF), RaDAR Rally, and Toilets on the Air.</p>
-    <p>As of the time of writing in August 2026, I think Spothole captures most radio programmes that have a
-        defined, downloadable reference list, and almost certainly those that have a spotting/alerting API. If you know
-        of one I've missed, please let me know!</p>
+    <p>As of the time of writing in August 2026, Spothole should capture most radio programmes that have a defined,
+        downloadable reference list, and almost certainly those that have a spotting/alerting API. If you know of one
+        that's missing, please let Spothole's developers know!</p>

 {% end %}
@@ -2,7 +2,7 @@
 {% block help_content %}

    <h2 class="mt-4">Thanks</h2>
-    <p>The software was written by <a href="https://ianrenton.com">Ian Renton, MØTRT</a> with code contributions by
+    <p>The software was written by <a href="https://ianrenton.com">Ian Renton, M0TRT</a> with code contributions by
        Steven, M1SDH.</p>
    <p>This project would not have been possible without those volunteers who have taken it upon themselves to run DX
        clusters, xOTA programmes, DXpedition lists, callsign lookup databases, solar conditions and propagation
@@ -14,7 +14,7 @@
        Norby LX1NO, Andrew VK3ARR, Mario DL4MFM, Mark M5TEA, Michael G7VJR, Rob G7LAS, Ed DD5LP, Raph F4LUB,
        Luc ON7KEC, Richard GD4OFB, Daniel PY2TDB, Alan VK1AO, Andrew WK1AD, Ullrich DF5WC, Wayne N3CDF, Jonathan G4IVV,
        Erik N2EPE, Sorin YO9TSN, Matt HB9HWI, Priit ES1TEB, Leigh KG7WED, Jouni OH3CUF, Onno VK6FLAB, Bruce WA7BNM, and
-        Larry F5PYI. (If I've forgotten you, let me know!)</p>
+        Larry F5PYI. (If you've been forgotten, please let Ian know!)</p>
    <p>Spothole is also dependent on a number of Python libraries, such as pyhamtools, and many JavaScript
        libraries, as well as the Font Awesome icon set and flag icons from the Noto Color Emoji set, and MIT-licenced
        GeoJSON files for CQ and ITU zones from HA8TKS.</p>
@@ -25,16 +25,16 @@
        it from a terminal with <code>telnet {{ telnet_server_address }} {{ telnet_server_port }}</code>.
    </li>
    {% end %}
-    <li>You can <b>write your own client using the Spothole API</b>, using the main Spothole instance to provide
-        data, and do whatever you like with it. The <a href="/help/usage/clients">Writing your own Client</a> page
-        contains guidance on how to do this, and the full API docs can be found <a href="/apidocs">here</a>. You can
-        also find reference implementations in the form
-        of Spothole's own web-based front end, plus my other two tools built on Spothole: <a
-                href="https://fieldspotter.radio">Field Spotter</a> and the <a href="https://qsomap.m0trt.radio">QSO
-            Map Tool</a>.
+    <li>You can <b>write your own client using the Spothole API</b>, using the main Spothole instance at
+        <a href="https://spothole.app">spothole.app</a> (or any other Spothole server) to provide data, and do whatever
+        you like with it. The <a href="/help/usage/clients">Writing your own Client</a> page contains guidance on how to
+        do this, and the full API docs can be found <a href="/apidocs">here</a>. You can also find reference
+        implementations in the form of Spothole's own web-based front end, plus two other tools by Spothole's developer
+        that are built on it: <a href="https://fieldspotter.radio">Field Spotter</a> and the <a
+                href="https://qsomap.m0trt.radio">QSO Map Tool</a>.
    </li>
    <li>If you want to <b>run your own version of Spothole</b> so you can customise the configuration, such as
-        enabling sources that I disable on the main instance, you can do that too. The <a
+        enabling sources that are disabled on the main instance, you can do that too. The <a
                href="/help/usage/running">Running your own Copy</a> page explains how to set up Spothole, and
        there are further pages on how to get it <a href="/help/usage/systemd">auto-starting with systemd</a>,
        <a href="/help/usage/nginx">using an nginx reverse proxy and setting up HTTPS support with certbot</a>, or
@@ -30,7 +30,8 @@
        "alerts"/"upcoming" page simply query the main spot API on a timer, whereas the spots, map and bands pages
        combine this approach with using the Server-Sent Events (SSE) endpoint to update live.
    </li>
-    <li>Let me know if you get stuck, I'm happy to help.</li>
+    <li>If you get stuck, get in touch with Spothole's developers who will be happy to help.
+    </li>
 </ul>
 <p>If you're fetching spot data, you're unlikely to need a sub-minute refresh time. For example, Spothole only queries
    the POTA API once every two minutes, so if your client is interested in POTA data there's no need to poll Spothole
@@ -43,9 +44,9 @@
 </p>
 <p>Remember, here at Spothole Inc. we offer an industry-standard "five nines" uptime on our server, with our own unique
    twist: we don't tell you which side of the decimal point the nines start! (Translation: This is a hobby project.
-    <code>spothole.app</code> runs on the same server as my blog and other stuff. It might go down without warning. By
-    all means base your own project on data from the main server if you like, but if you want any control over
-    reliability and downtime, please run your own copy instead.)</p>
+    <code>spothole.app</code> runs on the same server a Minecraft server and all sorts of other stuff. It might go down
+    without warning. By all means base your own project on data from the main server if you like, but if you want any
+    control over reliability and downtime, please run your own copy instead.)</p>

 <h3 class="mt-4" id="submitting-spots">Submitting Spots</h3>
 <p>As well as reading data, clients can submit new spots to Spothole using the "add spot" API endpoint, e.g.
@@ -53,45 +54,46 @@
    to other services such as the DX cluster. Check the <code>spot_allowed</code> and
    <code>spot_submit_providers</code> fields in the "options" API response to see what the server allows.</p>
 <p>To stop bots and spammers abusing the spotting function, a Spothole server can be configured to protect against this,
-    which means you will need an <strong>API key</strong>. API keys are issued by the operator of each Spothole server,
-    so get in touch with the server owner and let them know what your software is and how it will use the API. Once you
-    have a key, send it in the <code>X-API-Key</code> header of each add spot request. For example:</p>
+    which means you will need an <strong>API key</strong>. API keys are issued by the owner of each Spothole server,
+    not by the Spothole developer. This server is run by <strong>{{ server_owner_callsign }}</strong>, so get in touch
+    with them and let them know what your software is and how it will use the API. Once you have a key, send it in the
+    <code>X-API-Key</code> header of each add spot request. For example:</p>
 <pre><code>curl --request POST \
     --header "Content-Type: application/json" \
     --header "X-API-Key: your-api-key-here" \
     --data '{"spot":{"dx_call":"M0TRT","time":1760019539,"freq":14200000,"de_call":"M0TRT"}}' \
     https://spothole.app/api/v3/spot</code></pre>
 <p>Your API key identifies your software, so please keep it private. Don't commit it to a public code repository, and
-    don't embed it in JavaScript or anywhere else your users could extract it. If a key is misused, the server operator
+    don't embed it in JavaScript or anywhere else your users could extract it. If a key is misused, the server owner
    can revoke it, and spot submission from your client will stop working. Servers that don't protect spot submission
    don't need an API key, and will accept spots with or without one.</p>

 <h3 class="mt-4" id="terms">Conditions of Use</h3>
-<p>There are some simple, hopefully not onerous terms and conditions that you should agree to before writing a client
-    for the Spothole API. These probably aren't legally binding, and I'm just a random guy on the internet, I'm not
-    going to sue you for breaching them. But having these conditions in place ensures Spothole can continue to operate
-    without me burning out and with no payment required. In the collaborative and respectful tradition of amateur radio,
-    please read and understand them.</p>
+<p>The conditions are simple, and hopefully not onerous. They probably aren't legally binding, and nobody is likely to
+    sue you for breaching them. But having them in place ensures Spothole can continue to operate without the people
+    running it burning out, and with no payment required. In the collaborative and respectful tradition of amateur
+    radio, please read and understand them.</p>
 <p>When creating a Spothole client, you agree that:</p>
 <ul>
    <li>If you got an AI to write your code, and you run into problems, you will try to understand the code using your
-        Actual Intelligence before asking me for help. If you don't understand the code, please ask the AI to fix it,
-        not me.
+        Actual Intelligence before asking the developer or server owner for help. If you don't understand the code,
+        please ask the AI to fix it, not them.
    </li>
-    <li>When querying the API, you will send a useful referrer or user agent string that will help me uniquely identify
-        your software. This will allow me to diagnose the problem and figure out who to talk to if Spothole starts
-        receiving too many, or malformed, requests.
+    <li>When querying the API, you will send a useful referrer or user agent string that will help the server owner
+        uniquely identify your software. If their server starts receiving too many, or malformed, requests, this will
+        allow them to diagnose the problem and figure out who to talk to about it.
    </li>
    <li>You set a sensible query rate and will not try to take down the server by bombarding it with tons of requests.
    </li>
    <li>You are OK with the server being down occasionally. There is no uptime guarantee. This is a hobby project and
-        sometimes I will accidentally break stuff.
+        sometimes stuff will accidentally break.
    </li>
    <li>You check for API changes occasionally, e.g. using <a
            href="https://git.ianrenton.com/ian/spothole/releases.rss">the RSS feed for Spothole release
-        notifications</a>, or by <a href="https://mastodon.radio/@ian">following me on Mastodon</a>, or just by checking
-        back on the Spothole documentation every so often. I will do my best to stop updates breaking older client code,
-        but eventually I will need to turn off old versions of the API for my own sanity.
+        notifications</a>, or by <a href="https://mastodon.radio/@ian">following Spothole's developer on
+        Mastodon</a>, or just by checking back on the Spothole documentation every so often. Every effort is made to stop
+        updates breaking older client code, but eventually old versions of the API will need to be turned off for the
+        developer's sanity.
    </li>
 </ul>

@@ -8,11 +8,12 @@
 <p>The source code can be found at <a href="https://git.ianrenton.com/ian/spothole">https://git.ianrenton.com/ian/spothole</a>.
 </p>

-<p>I'm sorry this isn't on GitHub. There's too much noise on there now it's been given over to Copilot agents. If you
-    want to contribute code changes, that unfortunately means you'll have to sign up for an account on my Forgejo
-    server (linked above), or email me patch files the old-fashioned way. I'd hoped that Forgejo federation would be
-    working soon, so that at least you could use a Codeberg account rather than a new login specifically for my
-    instance, but unfortunately we're still waiting on that one!</p>
+<p>Sorry this isn't on GitHub. There's too much noise on there now it's been given over to Copilot agents. If you
+    want to contribute code changes, that unfortunately means you'll have to sign up for an account on the developer's
+    Forgejo server (linked above), or email patch files to <a href="https://ianrenton.com">Ian, M0TRT</a> the
+    old-fashioned way. The hope was that Forgejo federation would be working soon, so that at least you could use a
+    Codeberg account rather than a new login specifically for that instance, but unfortunately we're still waiting on
+    that one!</p>

 <h3 class="mt-4">Code structure</h3>
 <p>To navigate your way around the source code, this list may help.</p>
@@ -99,7 +100,7 @@
 <p>Finally, simply add the appropriate config to the <code>spot_providers</code> section of <code>config.yml</code>, and
    your provider should be
    instantiated on startup.</p>
-<p>The same approach as above is also used for alerts, and other types of providers. Give me a shout if you need any
-    advice.</p>
+<p>The same approach as above is also used for alerts, and other types of providers. Give Spothole's developers a shout
+    if you need any advice.</p>

 {% end %}
@@ -85,8 +85,8 @@
 }
 </code></pre>
 <p>One further change you might want to make to the file above is the <code>add_header
-    Access-Control-Allow-Origin</code> statements. These are what's used on my own Spothole server to make sure that
-    other third-party web-based software can get the data from my instance, and applies to any endpoint underneath
+    Access-Control-Allow-Origin</code> statements. These are what's used on the main <code>spothole.app</code> server to make
+    sure that other third-party web-based software can get the data from that instance, and applies to any endpoint underneath
    <code>/api</code>. If you want <em>your</em> Spothole instance to be set up the same way, so that others can write
    software in JavaScript that can access it, leave this intact. But if you want your Spothole instance to only be
    usable by scripts running on the web server you write, you can remove these lines. (Note that this doesn't stop
@@ -27,9 +27,9 @@ cp config-example.yml config.yml
 <p><code>config.yml</code> has an entry for a Clublog API key. If provided, this will allow Spothole to retrieve some
    more information about DX spots. The software will work just fine without it, but you may find a few country flags
    etc. are less accurate or missing. Clublog API keys are free, but you'll need to get your own by submitting a
-    helpdesk ticket and explaining what you'll use it for. The admin team are happy with the rate of requests made by my
-    Spothole server, so unless you change the source code of yours to radically increase the rate of querying Clublog,
-    I'm sure they will be fine with your server too.</p>
+    helpdesk ticket and explaining what you'll use it for. The admin team are happy with the rate of requests made by the
+    main <code>spothole.app</code> server, so unless you change the source code of yours to radically increase the rate
+    of querying Clublog, they should be fine with your server too.</p>
 <p>If your server is public and allows spots to be submitted, you may want to protect it from bots and spammers by
    setting <code>protect_spot_submission</code> to <code>true</code> and setting the reCAPTCHA keys in
    <code>config.yml</code>. Users of the web interface will then need to solve a CAPTCHA to submit a spot. Third-party
@@ -6,7 +6,7 @@
 <p>As well as a web interface and an HTTP API, Spothole offers a telnet server. This can be used to integrate Spothole's
    data into a traditional desktop logging program. The data Spothole produces is compatible with DXSpider, and
    therefore many loggers should accept it with no problems.</p>
-<p>This is a relatively new feature however, so if you run into problems, please do let me know.</p>
+<p>This is a relatively new feature however, so if you run into problems, please let Spothole's developers know.</p>
 <p>The one caveat with the Spothole telnet server is that <em>it does not support any commands</em>, other than
    <code>exit</code> or <code>bye</code>.
    You cannot therefore issue commands to retrieve past entries, set up filters, etc. If you need to filter the data,