Developer documentation

[John Hendrikx]

Apart from the first line which may have special significance, GitHub 
renders this nicely enough when you activate the preview.

I didn't mean to specifically suggest a special flavor of markdown, just 
that we should ensure it looks okay on GitHub as that will often be the 
viewer used.

--John

On 12/05/2023 23:00, Andy Goryachev wrote:
>
> Looks like JDK uses a different flavor of markdown:
>
> > % Testing the JDK
>
> https://github.com/openjdk/jdk/blob/38838b344af00b32251b3141350ba4deb3962d6f/doc/testing.md?plain=1#LL1C18-L1C18
>
> Are there any scripts that process the .md in jdk?
>
> -andy
>
> *From: *openjfx-dev <openjfx-dev-retn at openjdk.org> on behalf of Marius 
> Hanl <mariushanl at web.de>
> *Date: *Friday, May 12, 2023 at 13:57
> *To: *John Hendrikx <john.hendrikx at gmail.com>
> *Cc: *openjfx-dev at openjdk.org <openjfx-dev at openjdk.org>
> *Subject: *Aw: Developer documentation
>
> 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/20230513/fd8763d7/attachment-0001.htm>