<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body>
Yes, this seems like a good idea. I'm less sure about scattering
module-specific docs in the module dir, but let's start with a
top-level "doc" directory and see where we get. Also, I'd stick with
just Markdown for now.<br>
<br>
-- Kevin<br>
<br>
<br>
<div class="moz-cite-prefix">On 5/12/2023 1:57 PM, Marius Hanl
wrote:<br>
</div>
<blockquote type="cite" cite="mid:trinity-22613a6c-0cf6-4afe-bdf7-e7ef6a6d9764-1683925038025@3c-app-webde-bs12">
<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: <a class="moz-txt-link-freetext" href="https://github.com/openjdk/jdk/tree/master/doc">https://github.com/openjdk/jdk/tree/master/doc</a><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: <a class="moz-txt-link-freetext" href="https://github.com/openjdk/jdk/blob/master/doc/building.md">https://github.com/openjdk/jdk/blob/master/doc/building.md</a><br>
And: <a class="moz-txt-link-freetext" href="https://github.com/openjdk/jdk/blob/master/doc/building.html">https://github.com/openjdk/jdk/blob/master/doc/building.html</a></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"
<a class="moz-txt-link-rfc2396E" href="mailto:john.hendrikx@gmail.com"><john.hendrikx@gmail.com></a><br>
<b>An:</b> <a class="moz-txt-link-abbreviated" href="mailto:openjfx-dev@openjdk.org">openjfx-dev@openjdk.org</a><br>
<b>Betreff:</b> Developer documentation</div>
<div name="quoted-content">In PR <a href="https://github.com/openjdk/jfx/pull/910" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">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>
</blockquote>
<br>
</body>
</html>