Download FreeBSD: headings, redundancy, clarity

[grahamperrin]

Summary

https://www.freebsd.org/where/

Level 1 heading 'Download FreeBSD' is not perceptibly different from the identically-worded visible title with a single sentence between the two. This heading appears to be redundant.

The very short 'Help to Test' section is no more than direction to visit the download page. Nonsense, we're already at the download page.

Generally, the page has become a slightly disorderly mix: choices, production quality (RELEASE), beta, development, snapshots, CURRENT, STABLE, general information, purchasing (RELEASE, presumably), archaic stuff, current stuff (derivatives (non-Project)), current stuff (ports (within the FreeBSD Project)). Begin improving this, partly through adjustments to heading levels.

Two new headings, level 1:

Production Quality

Development and Testing

… and so on.

Test Plan

Preview in GitHub: https://github.com/grahamperrin/freebsd-doc/blob/where-2022-11-02/website/content/en/where.adoc.

[grahamperrin]

website/content/en/where.adoc

36

I forgot, Americanisation. should probably be uppercase Q in a heading.

144

… should probably be Testing (uppercase T) in a heading.

[grahamperrin]

The Development and Testing preamble is intentionally terse, but (necessarily) slightly technical. Essentially:

• drop a hint that release is not always (production quality) release
• drop a hint to reduce the likelihood of people aiming for something current, i.e. latest, without understanding the special meaning of the word.

There's the temptation to say more in this preamble, let's not.

(More can be said, and pictured, elsewhere.)

website/content/en/where.adoc

148

Superflous; delete.

Already stated: not intended for use in production environments

[pauamma_gundo.com]

website/content/en/where.adoc

146

"prerelease", to me, implies "being actively prepared for actual release". Hence, BETA-n and RC-n are, -current definitely isn't by my lights. I have no opinion about -stable inbetween minor releases. Perhaps "Versions not intended for use..."?

150

I don't think we have user-visible alphas at this time.

158

I'd also mention -STABLE here.

(And "People looking for the... most likely want... " to avoid "you".)

160

I'd link to the Handbook here for an explanation.

253–265

Should that even be on this page, instead of under https://www.freebsd.org/ports/?

[gjb]

Approved, regardless of in-line comment above.

website/content/en/where.adoc

242

We can probably get rid of the NFS reference here.

[grahamperrin]

website/content/en/where.adoc

146

For 13.1, PRERELEASE preceded BETA1.

That's not intended to answer the question, however it might be a good example of ways in which FreeBSD can surprise people.

Certainly, we can improve people's understandings by having clearer explanations – anything in-depth can be kept away from the 'Get FreeBSD' page – but for now, I reckon, it's true enough to state that a release candidate is not intended for use in production.

I'll enjoy a longer conversation about this, maybe in IRC. Thanks, folks.

150

True, however this is general text – intentionally not changing, conditionally, when things appear then disappear.

158

RELEASE is likeliest.

In this case, wording is intentionally personal.

160

Restraint here was intentional.

The page already begins with a general link to Release Information | The FreeBSD Project, where links to the FreeBSD Handbook – for STABLE and CURRENT – are fairly prominent.

242

Done at https://github.com/grahamperrin/freebsd-doc/commit/407882470db5c3977d3c91521516acc60da596c1, it'll be included when I push to freebsd HEAD:main.

There remains a "Huh?" aspect to this section of the page, we can aim to make things crystal clear at a later date.

253–265

I do plan to:

1. improve About FreeBSD Ports | The FreeBSD Project, by (at least) moving the essence of what's highlighted
2. further condense this download/get/where page by moving the essence of some other content (e.g. the derived/distro stuff).

---

The restraint here in D37235 was to simplify review, and so, expedite approval. Essentially:

• the duplicate headings, obviously wrong, which have annoyed me for a long time
• the self-referencing nonsense, which stuck out like a sore thumb when I thought of preparing for links to 12.4-RELEASE.

---

Looking ahead:

• aim for this page to convey, more clearly, in as few words as possible:
  • what you get with the OS
  • what's additional (not included)
  • where to get additions
• assume that some readers will be blind to the sidebar (with Ported Applications at its foot, but nothing about getting stuff that's based on the OS)
• more broadly, assume no sidebar.

[grahamperrin]

Trailing white spaces (my usual mistake) fixed prior to commit.

---

https://reviews.freebsd.org/R9:5c8cc20333c4e87dd5d3a562ad87f5c18254d5fd
https://cgit.freebsd.org/doc/commit/?id=5c8cc20333c4e87dd5d3a562ad87f5c18254d5fd
https://codeberg.org/FreeBSD/freebsd-doc/commit/5c8cc20333c4e87dd5d3a562ad87f5c18254d5fd
https://github.com/freebsd/freebsd-doc/commit/5c8cc20333c4e87dd5d3a562ad87f5c18254d5fd
https://gitlab.com/FreeBSD/freebsd-doc/-/commit/5c8cc20333c4e87dd5d3a562ad87f5c18254d5fd

website/content/en/where.adoc

2

For a future revision: instead of Download FreeBSD, a better title for the page might be Get FreeBSD. This would, at least, match the phrase that's used at the home page to link here.

(Some of what's here – purchasing a disc from FreeBSD Mall, for example – does not involve any download by the reader.)

The title was no different at the time of migration to Hugo and AsciiDoctor. I wonder whether it was Get FreeBSD at any time prior to that, I don't intend to dig.

139–144

Post-commit, a cosmetic issue: no visible white space between the table and the level 1 heading that's below.

[grahamperrin]

5c8cc20333c4e87dd5d3a562ad87f5c18254d5fd must be fixed, I'll open a simple review for the heading section levels alone.

website/content/en/where.adoc

277–281

Post-commit, a cosmetic issue: again, white space (an empty line) marked up, but no visible white space above what I thought was a level 1 heading:

Now, reading Markdown syntax alongside https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#section-titles, I see:

• Markdown for level 1 (headings) is treated as level 0 (section) in AsciiDoc

– and section 0, equal to a title, must occur no more than once in an article, and so on.

[grahamperrin]

In D37235#847543, @grahamperrin wrote:

5c8cc20333c4e87dd5d3a562ad87f5c18254d5fd must be fixed, …

https://reviews.freebsd.org/D37307 ready for review.

[grahamperrin]

Three comments done, through faba218b9283 for D37307.

---

Styles of headings

Now, looking at Get FreeBSD | The FreeBSD Project: to my eye, the styles of heading levels 2 and 3 (resulting from AsciiDoc section levels 1 and 2) are no different from the style of heading 1 for the title. I'll have a chat, initially with @carlavilla, about possible future enhancements in this area.

Reviews and content

@gjb thanks again for approvals (and for mentoring) at so busy a time. faba218b9283 omitted to show you as (mentor), sorry.

@pauamma thanks again for suggestions, particularly around the meanings of prerelease et cetera. For discussions ahead of future reviews, we should rope in @koobs and others – Kubilay is, memorably, given credit for the second of the images at https://forums.freebsd.org/posts/564808.