Improve README documentation clarity#11682
Conversation
| [][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 |
There was a problem hiding this comment.
we use such sentence in many place .... I would like to first discuss, confirm it on ML
Next we should change it globally
There was a problem hiding this comment.
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
left a comment
There was a problem hiding this comment.
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.
|
|
||
|
|
||
| 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 |
There was a problem hiding this comment.
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.
This pull request improves the clarity of the README documentation by refining wording.
No functional or behavioral changes are introduced.
Checklist:
Licensing: