(maven-shared-utils) branch master updated: Rewrite documentation per ASD-STE100 Simplified Technical English (#418)

[el...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

elharo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-shared-utils.git


The following commit(s) were added to refs/heads/master by this push:
     new e8c61b5  Rewrite documentation per ASD-STE100 Simplified Technical English (#418)
e8c61b5 is described below

commit e8c61b518ca52f90a91e62e9f789b4dc822eff19
Author: Elliotte Rusty Harold <el...@users.noreply.github.com>
AuthorDate: Tue Aug 4 10:52:31 2026 +0000

    Rewrite documentation per ASD-STE100 Simplified Technical English (#418)
    
    Co-authored-by: opencode <op...@example.com>
---
 src/site/apt/index.apt.vm     | 15 +++++----------
 src/site/xdoc/download.xml.vm | 14 ++++++--------
 2 files changed, 11 insertions(+), 18 deletions(-)

diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm
index 18ce056..6fde828 100644
--- a/src/site/apt/index.apt.vm
+++ b/src/site/apt/index.apt.vm
@@ -29,14 +29,11 @@
 
 ${project.name}
 
-   This project aims to be a functional replacement for
-   {{{https://codehaus-plexus.github.io/plexus-utils/}plexus-utils}} in Maven.
-   
-   It is not a 100% API compatible replacement though but a replacement <with improvements>:
-   lots of methods got cleaned up, generics got added and we dropped a lot of unused code.
+   This project replaces {{{https://codehaus-plexus.github.io/plexus-utils/}plexus-utils}} for Maven.
 
-   Then there are additions, like
-   {{{./apidocs/org/apache/maven/shared/utils/logging/package-summary.html}styled message API}}.
+   It is not a 100% API compatible replacement. We cleaned up methods, added generics, and removed unused code.
+
+   This project adds new features, like {{{./apidocs/org/apache/maven/shared/utils/logging/package-summary.html}styled message API}}.
 
 Why?
 
@@ -45,8 +42,6 @@ Why?
 
 Why not commons?
 
-    We would prefer code to use commons-* where appropriate, but plexus-utils became
-    slightly incompatible from the Commons versions over the years, so migrating is not
-    always a 1:1 operation. Migrating to Maven Shared Utils is a 1:1 operation in most cases.
+    We prefer code to use commons-* where appropriate. The plexus-utils versions became incompatible with the Commons versions over time. Migrating is not always a 1:1 operation. Migrating to Maven Shared Utils works in most cases as a 1:1 operation.
 
   []
diff --git a/src/site/xdoc/download.xml.vm b/src/site/xdoc/download.xml.vm
index 2b848a9..1e1e6a3 100644
--- a/src/site/xdoc/download.xml.vm
+++ b/src/site/xdoc/download.xml.vm
@@ -29,9 +29,9 @@ under the License.
 
       <p><strong>${project.name} ${project.version}</strong> is distributed in source format.</p>
 
-      <p>Use a source archive if you intend to build <strong>${project.name}</strong> yourself.</p>
+      <p>Use a source archive if you want to build ${project.name} yourself.</p>
 
-      <p>Otherwise, simply use the ready-made binary artifacts from <strong>central repository</strong>.</p>
+      <p>Otherwise, use the ready-made binary artifacts from the central repository.</p>
 
       <p><strong>${project.name}</strong> is distributed under the <a href="https://www.apache.org/licenses/">Apache License, version 2.0</a>.</p>
 
@@ -58,16 +58,14 @@ under the License.
           </tbody>
         </table>
 
-        <p>It is essential that you <a href="https://www.apache.org/info/verification.html">verify the integrity</a> of the downloaded file
-          using the checksum (.sha512 file)
-          or using the signature (.asc file) against the public <a href="https://downloads.apache.org/maven/KEYS">KEYS</a> used by the Apache Maven developers.
-        </p>
+        <p>You must verify the integrity of the downloaded file using the checksum (.sha512 file) or using the signature (.asc file).</p>
+        <p>Use the public KEYS that Apache Maven developers provide to verify.</p>
 
       </subsection>
 
       <subsection name="Previous Versions">
-        <p>It is strongly recommended to use the latest release version of <strong>${project.name}</strong> to take advantage of the newest features and bug fixes.</p>
-        <p>Older non-recommended releases can be found on our <a href="https://archive.apache.org/dist/maven/shared/">archive site</a>.</p>
+        <p>You must use the latest release version of ${project.name} to get new features and bug fixes.</p>
+        <p>Older releases exist on the archive site. These releases are not recommended.</p>
       </subsection>
     </section>
   </body>