On Sat, Oct 24, 2026 at 11:44:08AM +0000, Björn Raupach wrote: > Documentation is all about content and structure. > > The official Maven documentation at https://maven.apache.org/ has lots of > great content but it lacks structure. It is hard to navigate. There are so > many topics thrown at you, which most of the average users don’t need or care > about. It is written by technical people for technical people. User guides, > plugins development and Maven internals are not well separated from each > others. Should be. Make it much more readable.
Seconded. One thing I've found to work well is to consider separate views of the product for different needs. In ye olden days both DEC and IBM (and likely others) would issue two manuals for a product: a Reference and a User's Guide. The Reference is for when "I want to see everything the product does, feature by feature, because I'm looking for complete information on something specific" and the Guide is for when "I want to know good ways of thinking about the product as I apply it to my task." In my own work on documentation (elsewhere) I've found that disentangling reference and advice makes documentation clearer and more easily navigable. -- Mark H. Wood Lead Technology Analyst University Library Indiana University Indianapolis 755 W. Michigan Street Indianapolis, IN 46202 317-274-0749 library.indianapolis.iu.edu ORCiD: 0000-0002-9558-3768
binrb_DlEj7gc.bin
Description: PGP Key 0xDA186C80E6EEA295.
signature.asc
Description: PGP signature
