scala-native
ReadTheDocs needs at least two improvements.
This is a placeholder, in the hopes that I can make time to do these improvements. Yes, I should be glad that there are any SN docs at all. Seeking to iteratively improvement is my paying tribute to their existence and utility, and to the time people have invested in them.
Today I had to consult the ReadTheDocs documentation (v.latest, date unknown but probably 4 or 5 months old). It has been awhile since I have had to read the landing page. I may not have had "beginner's eyes" but they were fresher than my usual rush. I noticed a few opportunities for improvement.
-
The first page of the SN ReadTheDocs desperately needs a publication date. This could stand in for a proper version number.
This will become increasingly useful/necessary as the changes to do (and publish?) a nightly build become available.
-
The "Supported versions" on the landing page is grossly out of date. It describes the latest Scala Native version as 0.4.3 with ancient Scala Versions. The full table should probably be an Appendix, with only a short table or paragraph giving the current SN version and supported Scala Versions (and pointer to Appendix for older versions).
Something to explore, whilst waiting for CI to complete:
reStructuredText (.rst) has a (date)[https://docutils.sourceforge.io/docs/ref/rst/directives.html#date] directive:
.. |date| date::
.. |time| date:: %H:%M
The 2023-07-17 format is probably good, as is, for an international audience ( anything but ambiguous m/d/y or is it d/m/y?). The hours and minutes would probably need a timezone, if possible.