<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>