<html><head></head><body><div style="font-family: Verdana;font-size: 12.0px;"><div>I like this idea as well. And I agree, especially the snapping insight are good to document as this topic really isn't trivial.<br/>
I think we should stick to the official JDK, which also follows the idea suggested by John.<br/>
See here: https://github.com/openjdk/jdk/tree/master/doc<br/>
-> There is a doc folder in the root directory.</div>
<div><br/>
The JDK decided to always have a .md as well as a .html file.<br/>
See: https://github.com/openjdk/jdk/blob/master/doc/building.md<br/>
And: https://github.com/openjdk/jdk/blob/master/doc/building.html</div>
<div><br/>
+1 for the Markdown format (.md). IntelliJ is also able to render this format.</div>
<div>
<div> </div>
<div>-- Marius</div>
<div>
<div name="quote" style="margin:10px 5px 5px 10px; padding: 10px 0 10px 10px; border-left:2px solid #C3D9E5; word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;">
<div style="margin:0 0 10px 0;"><b>Gesendet:</b> Freitag, 12. Mai 2023 um 21:02 Uhr<br/>
<b>Von:</b> "John Hendrikx" <john.hendrikx@gmail.com><br/>
<b>An:</b> openjfx-dev@openjdk.org<br/>
<b>Betreff:</b> Developer documentation</div>
<div name="quoted-content">In PR <a href="https://github.com/openjdk/jfx/pull/910" target="_blank">https://github.com/openjdk/jfx/pull/910</a> a lot of "new" insights<br/>
were gained in the snapping logic. Michael Strauss suggested<br/>
documenting this, and I thought we may as well discuss this on the<br/>
mailing list instead of continuing the discussion in that PR.<br/>
<br/>
In my normal line of work, I usually encourage projects to include<br/>
developer documentation as part of the Git repository. This allows any<br/>
developer to access and modify the documentation easily, and allows you<br/>
to keep documentation in sync with relevant commits (and one can ask<br/>
developers to do so as part of the PR).<br/>
<br/>
The documentation is provided in markdown format and is usually stored<br/>
in a /doc folder. If there are multiple modules, there can be<br/>
specialized doc folders per module with a top level doc folder which<br/>
contains an index.md linking all the docs together, and containing<br/>
documentation that is not module specific.<br/>
<br/>
The documentation is intended for developers only, not for users of<br/>
JavaFX, and hence does not need to be published. Markdown files can<br/>
either be read directly in your IDE of choice or online via GitHub/GitLab.<br/>
<br/>
The build documentation may be a good candidate to place there as well.<br/>
<br/>
So, my suggestion would be:<br/>
<br/>
- Create a top level /doc folder, and create module level /doc folders<br/>
as needed when relevant documentation is written<br/>
- In each /doc folder there is an index.md file that links to all<br/>
documentation in that folder<br/>
- A higher level index.md also contains links to child indexes<br/>
- Consider moving the build and any onboarding documentation there<br/>
- The top level README.md should have a link to /doc/index.md<br/>
- Use only GitHub supported markdown features<br/>
<br/>
--John<br/>
<br/>
<br/>
</div>
</div>
</div>
</div></div></body></html>