<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
@font-face
{font-family:"Times New Roman \(Body CS\)";
panose-1:2 11 6 4 2 2 2 2 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
font-size:10.0pt;
font-family:"Calibri",sans-serif;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
span.EmailStyle19
{mso-style-type:personal-reply;
font-family:"Courier New";
color:windowtext;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;
mso-ligatures:none;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style>
</head>
<body lang="EN-US" link="blue" vlink="purple" style="word-wrap:break-word">
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New"">I think this is a great idea!<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New"">Some projects use a separate wiki, but sometimes it backfires when domain name changes or wiki software gets updated.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New"">Making certain parts of documentation such as these notes, a part of the code repository not only eliminates these failure modes, but provides additional benefit of doc review along
with the code review, documentation in sync with the code, and ability to diff the changes.
<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New"">Github markdown is a fairly new feature, sometimes a bit complicated to use (tables), but it does get rendered by Github and some IDEs (Eclipse, for example).<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New"">I second John's suggestion, but also I am curious as to what other people think.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New"">-andy<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New""><o:p> </o:p></span></p>
<div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal" style="margin-bottom:12.0pt"><b><span style="font-size:12.0pt;color:black">From:
</span></b><span style="font-size:12.0pt;color:black">openjfx-dev <openjfx-dev-retn@openjdk.org> on behalf of John Hendrikx <john.hendrikx@gmail.com><br>
<b>Date: </b>Friday, May 12, 2023 at 12:02<br>
<b>To: </b>openjfx-dev@openjdk.org <openjfx-dev@openjdk.org><br>
<b>Subject: </b>Developer documentation<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal" style="margin-bottom:12.0pt"><span style="font-size:11.0pt">In PR
<a href="https://github.com/openjdk/jfx/pull/910">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>
<o:p></o:p></span></p>
</div>
</div>
</body>
</html>