Aw: Developer documentation

[Kevin Rushforth]

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.

-- Kevin


On 5/12/2023 1:57 PM, Marius Hanl wrote:
> I like this idea as well. And I agree, especially the snapping insight 
> are good to document as this topic really isn't trivial.
> I think we should stick to the official JDK, which also follows the 
> idea suggested by John.
> See here: https://github.com/openjdk/jdk/tree/master/doc
> -> There is a doc folder in the root directory.
>
> The JDK decided to always have a .md as well as a .html file.
> See: https://github.com/openjdk/jdk/blob/master/doc/building.md
> And: https://github.com/openjdk/jdk/blob/master/doc/building.html
>
> +1 for the Markdown format (.md). IntelliJ is also able to render this 
> format.
> -- Marius
> *Gesendet:* Freitag, 12. Mai 2023 um 21:02 Uhr
> *Von:* "John Hendrikx" <john.hendrikx at gmail.com>
> *An:* openjfx-dev at openjdk.org
> *Betreff:* Developer documentation
> In PR https://github.com/openjdk/jfx/pull/910 a lot of "new" insights
> were gained in the snapping logic.  Michael Strauss suggested
> documenting this, and I thought we may as well discuss this on the
> mailing list instead of continuing the discussion in that PR.
>
> In my normal line of work, I usually encourage projects to include
> developer documentation as part of the Git repository. This allows any
> developer to access and modify the documentation easily, and allows you
> to keep documentation in sync with relevant commits (and one can ask
> developers to do so as part of the PR).
>
> The documentation is provided in markdown format and is usually stored
> in a /doc folder. If there are multiple modules, there can be
> specialized doc folders per module with a top level doc folder which
> contains an index.md linking all the docs together, and containing
> documentation that is not module specific.
>
> The documentation is intended for developers only, not for users of
> JavaFX, and hence does not need to be published. Markdown files can
> either be read directly in your IDE of choice or online via GitHub/GitLab.
>
> The build documentation may be a good candidate to place there as well.
>
> So, my suggestion would be:
>
> - Create a top level /doc folder, and create module level /doc folders
> as needed when relevant documentation is written
> - In each /doc folder there is an index.md file that links to all
> documentation in that folder
> - A higher level index.md also contains links to child indexes
> - Consider moving the build and any onboarding documentation there
> - The top level README.md should have a link to /doc/index.md
> - Use only GitHub supported markdown features
>
> --John
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/openjfx-dev/attachments/20230512/12894fa6/attachment-0001.htm>