Skip to content

Improve README documentation clarity#11682

Open
amahi1568 wants to merge 1 commit into
apache:masterfrom
amahi1568:fix-docs
Open

Improve README documentation clarity#11682
amahi1568 wants to merge 1 commit into
apache:masterfrom
amahi1568:fix-docs

Conversation

@amahi1568

Copy link
Copy Markdown

This pull request improves the clarity of the README documentation by refining wording.
No functional or behavioral changes are introduced.

Checklist:

  • This pull request addresses just one issue and does not include unrelated changes.
  • Each commit has a meaningful subject and body.
  • Unit tests were added or updated where applicable (not applicable for documentation-only changes).
  • mvn verify was run (not required for documentation-only changes).
  • Core ITs were run (not applicable).

Licensing:

  • I hereby declare this contribution to be licensed under the Apache License Version 2.0, January 2004.
  • In any other case, an Apache Individual Contributor License Agreement (ICLA) has been filed.

Comment thread README.md
[![Java CI](https://github.com/apache/maven/actions/workflows/maven.yml/badge.svg?branch=maven-3.9.x)][gh-build-3.9]

Apache Maven is a software project management and comprehension tool. Based on
Apache Maven is a software project management and build automation tool. Based on

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we use such sentence in many place .... I would like to first discuss, confirm it on ML
Next we should change it globally

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We've discussed it before. I'd prefer not to let the perfect be the enemy of the good. Fixing one awkward, unclear doc out of 100 is better than leaving it alone while we figure out how to fix the other 99. Since we're not a mono-repo we'll never fix them all at the same time anyway.

@gnodet gnodet left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude Code on behalf of Guillaume Nodet

The phrase "software project management and comprehension tool" is Maven's long-standing canonical description, used consistently on the Maven website and across official documentation. While "build automation" is how many people think of Maven in practice, the word "comprehension" was chosen deliberately to convey that Maven is about more than just building — it also helps developers understand a project (dependencies, structure, reports, documentation).

I'd recommend closing this PR as the current wording is intentional, not unclear.

Comment thread README.md


Apache Maven is a software project management and comprehension tool. Based on
Apache Maven is a software project management and build automation tool. Based on

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This changes Maven's canonical self-description. The phrase "software project management and comprehension tool" has been Maven's official tagline for over 20 years (see maven.apache.org). The word "comprehension" is intentional — it refers to Maven's ability to help developers understand a project (dependency tree, reports, site docs), not just build it.

Replacing it with "build automation" narrows the meaning and diverges from the project's established identity. I would keep the original wording.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants