RFR: Initial section on testing [v6]

Igor Ignatyev iignatyev at openjdk.java.net
Thu Oct 22 21:15:17 UTC 2020


On Thu, 22 Oct 2020 19:43:24 GMT, Lance Andersen <lancea at openjdk.org> wrote:

> In my opinion only docs that are tied to a specific version of the source code should be in the /doc/ directory.

Unfortunately, any useful documentation will become tied to a specific version, and the Guide already is: you refer to a specific directory layout, the layouts are different in different versions of JDK, tip vs 8u vs 11u; the list of supported test harnesses is version-dependent; even recommendations and some of the best practices are version-dependent; as the presence and content of `/doc`; ... thus, according to your logic, the Guide must be in `/doc`, which, I guess, would make it harder "to find documentation on-line". 

Actually, I have a slightly different opinion on the whole hypothesis where people expect to find documentation these days. Although it's true for in general people do that online, the information in this Guide and the other related documentation isn't generic information, it's the information for developers. From my experience, most developers expect to find all the needed documentation within their local workspace, not on some _external_ sources. This isn't to say that hosting the same (or similar) documentation on web-servers is useless, it's just not the 1st place I and, I believe, many others would start their search.

> We already have too many different documents and nobody can find any information. We need to consolidate and reduce the number of places, not add more.

that, I totally agree with, but my gut feeling is what the root cause of this problem is the absence of a well-known entry point and poor structure of the documentation. the guide might be such an entry point, or it can be `CONTRIBUTING.md` or `README.md` in the repo.

-- Igor

-------------

PR: https://git.openjdk.java.net/guide/pull/30


More information about the guide-dev mailing list