RFR: Initial section on testing [v2]
Jesper Wilhelmsson
jwilhelm at openjdk.java.net
Mon Oct 19 21:07:10 UTC 2020
On Fri, 16 Oct 2020 17:12:56 GMT, Igor Ignatyev <iignatyev at openjdk.org> wrote:
> Although I understand the desire to have as much relative information in the guide, I don't think we need to repeat
> ourselves, most of the information presented here is already available in `doc/testing.md` and
> `doc/hotspot-unit-tests.md`. the former document provides more comprehensive documentation about all
> available/supported testing in OpenJDK, different modes of test execution; the latter gives an overview of different
> `TEST*` macros available in hotspot gtest, defines _good_ tests, provides guidelines on writing such tests, etc. I
> think we need to find some middle ground here, so we won't duplicate documentation and at the same time, we won't force
> people to gather required information from N different places. With that in mind, I think it's important to 1st define
> the goal of 'testing' section of the Guide.
The documents in /doc/ requires prior knowledge to understand. Those aren't written for beginners. The goal for the
guide in this case is to provide quick links to more information and serve as a buffer to fill in the gaps for a first
time tester.
I agree that we should avoid duplication. For the Developers' Guide I want to have just enough information to get
everything up and running. For any additional information there should be links to more detailed documentation.
Personally I have issues with documentation that requires knowledge not only to understand, but also to access. But as
the source is now on GitHub and the .md files are reasonably readable through the web interface it's at least possible
to link to them. I don't know if search engines will index the JDK source code though so for people googling for
documentation we still need some indexed document that refers to these documents.
-------------
PR: https://git.openjdk.java.net/guide/pull/30
More information about the guide-dev
mailing list