FreeBSD Handbook: Appendix C: updates and corrections #224

grahamperrin · 2023-07-15T20:22:21Z

Affected:

Appendix C. Resources on the Internet | FreeBSD Documentation Portal

Preview in GitHub:

https://github.com/grahamperrin/freebsd-doc/blob/bug-264754/documentation/content/en/books/handbook/eresources/_index.adoc

Hello, 2023. Remove the opening paragraph, which, many years ago, might have helped readers to understand why electronic media became more suitable than paper for FreeBSD Project enlightenment.

Be concise, not repetitive:

with 'Websites' as the subheading within the FreeBSD Handbook – and with 'Forums' and 'FreeBSD' within the name of The FreeBSD Forums – there's no need to describe The FreeBSD Forums as a web based discussion forum for FreeBSD

… and so on.

Expand, reorder and rewrite the list of websites.

Internet Relay Chat is a communication protocol that does not use HTTP or HTTPS; it's not a website. Make it separate from the websites section.

Below the separate section for Internet Relay Chat, add a hidden section in readiness for Matrix.

Refer to the Postmaster Team section of FreeBSD Project Administration and Management.

NNTP groups content reviewed. Delist some.

Reduce bullet point overload.

Make more use of normal paragraphs.

FreeBSD bug 264754 – FreeBSD Handbook: Appendix C: updates and corrections

Be concise, not repetitive. With 'Websites' as a subheading within the FreeBSD Handbook – and with Forums and FreeBSD within the name of The FreeBSD Forums – there's no need to describe The FreeBSD Forums as a web based discussion forum for FreeBSD … and so on. Expand, reorder and rewrite the list of websites. Internet Relay Chat is a communication protocol that does not use HTTP or HTTPS; it's not a website. Make it separate. Below the separate section for Internet Relay Chat, add a hidden section in readiness for Matrix.

Be concise. It's 2023, the Project has transitioned to Git, I doubt that anyone needs the hint about electronic media becoming more practical than print. Remove the opening paragraph.

Various improvements.

In the context of FreeBSD mailing list rules, do not promote the mailto: URL for the Postmaster Team. Instead, refer to the Postmaster Team section of FreeBSD Project Administration and Management.

Remove trailing whitespace. One sentence per line.

Rationalise white space above and below a comment block.

Remove my wiki-welated weasel words.

Reduce bullet point overload. Make more use of normal paragraphs.

Delist comp.unix.misc, which has nothing UNIX-related in the past eleven months.

De-list comp.unix.questions, which had only three UNIX-related threads this year.

grahamperrin · 2023-07-16T10:05:00Z

documentation/content/en/books/handbook/eresources/_index.adoc

 * link:news:comp.unix[comp.unix]
-* link:news:comp.unix.questions[comp.unix.questions]
 * link:news:comp.unix.admin[comp.unix.admin]
 * link:news:comp.unix.programmer[comp.unix.programmer]
 * link:news:comp.unix.shell[comp.unix.shell]
-* link:news:comp.unix.misc[comp.unix.misc]
 * link:news:comp.unix.bsd[comp.unix.bsd]


Is it worth noting that comp.unix and comp.unix.bsd are points in a hierarchy, but not groups?

grahamperrin · 2023-07-16T10:08:11Z

documentation/content/en/books/handbook/eresources/_index.adoc

 * link:news:comp.unix.admin[comp.unix.admin]
 * link:news:comp.unix.programmer[comp.unix.programmer]
 * link:news:comp.unix.shell[comp.unix.shell]
-* link:news:comp.unix.misc[comp.unix.misc]


comp.unix.misc (delisted) visual overview:

grahamperrin · 2023-07-16T10:09:39Z

documentation/content/en/books/handbook/eresources/_index.adoc


 * link:news:comp.unix[comp.unix]
-* link:news:comp.unix.questions[comp.unix.questions]


comp.unix.questions (delisted) visual overview:

grahamperrin · 2023-07-16T10:13:56Z

documentation/content/en/books/handbook/eresources/_index.adoc

-* link:news:de.comp.os.unix.bsd[de.comp.os.unix.bsd] (German)
-* link:news:fr.comp.os.bsd[fr.comp.os.bsd] (French)
+* link:news:comp.unix.bsd.freebsd.announce[comp.unix.bsd.freebsd.announce] -- FreeBSD-specific
+* link:news:comp.unix.bsd.freebsd.misc[comp.unix.bsd.freebsd.misc] -- FreeBSD-specific


comp.unix.bsd.freebsd.misc visual overview:

thirteen on-topic threads this year

overall, probably not bad enough to justify delisting.

grahamperrin · 2023-07-16T10:16:29Z

documentation/content/en/books/handbook/eresources/_index.adoc


 * link:news:comp.unix[comp.unix]
-* link:news:comp.unix.questions[comp.unix.questions]
 * link:news:comp.unix.admin[comp.unix.admin]
 * link:news:comp.unix.programmer[comp.unix.programmer]


comp.unix.programmer visual overview:

twelve on-topic threads this year

overall, probably not bad enough to justify delisting.

grahamperrin · 2023-07-16T10:17:50Z

documentation/content/en/books/handbook/eresources/_index.adoc


 * link:news:comp.unix[comp.unix]
-* link:news:comp.unix.questions[comp.unix.questions]
 * link:news:comp.unix.admin[comp.unix.admin]
 * link:news:comp.unix.programmer[comp.unix.programmer]
 * link:news:comp.unix.shell[comp.unix.shell]


comp.unix.shell visual overview:

good enough to remain.

grahamperrin · 2023-07-16T10:19:28Z

documentation/content/en/books/handbook/eresources/_index.adoc

 * link:news:comp.unix.bsd[comp.unix.bsd]

-=== X Window System
+=== The X Window System

 * link:news:comp.windows.x[comp.windows.x]


comp.windows.x visual overview:

good enough to remain.

Add: The Mail Archive. Add: a brief comparison of listed archives (a two-message example).

The existing points about FreeBSD-provided mail archives are better placed under the new paragraph about comparisons.

Markup: - '--' instead of '–' - <https://bugs.freebsd.org/266881> to remind me of [.filename]#/path/to/file#. Clarity: - be explicit about the text/plain nature of the non-large attachments.

Simplify, clarify: numbers 1 and 2 for the two list items.

sergio-carlavilla · 2023-07-29T08:34:14Z

Before making the commit open a review in phabricator please

grahamperrin · 2023-07-29T13:10:15Z

documentation/content/en/books/handbook/eresources/_index.adoc


 Before posting to any list, please:

-* learn about how to best use the mailing lists, such as how to help avoid frequently-repeated discussions, by reading the extref:{mailing-list-faq}[Mailing List Frequently Asked Questions] (FAQ) document
+* learn about how to best use the lists, such as how to help avoid frequently-repeated discussions, by reading the extref:{mailing-list-faq}[Mailing List Frequently Asked Questions] (FAQ) document
 * search the archives, to tell whether someone else has already posted what you intend to post.

 Archive search interfaces include: 

 - https://lists.freebsd.org/search[] (FreeBSD, experimental)


https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=264754#c12 asked (added emphasis):

(In reply to Graham Perrin from comment #10)

(In reply to Sergio Carlavilla Delgado from comment #6)

https://lists.freebsd.org/search was recently promoted without the promoter(s) describing it as experimental.

Should we cease to describe it as experimental under https://docs.freebsd.org/en/books/handbook/eresources/#eresources-mail?

grahamperrin · 2023-07-29T13:48:32Z

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=264754#c14 presented

197d892 Handbook: Internet resources: opening paragraphs

… Rewrite the first two paragraphs. Some of what's here belongs elsewhere in the FreeBSD Handbook, but it's a start.

Rapidity of development (the area highlighted in yellow) is not an Internet resource.

Via https://www.freebsd.org/releng/#docs:

FreeBSD Release Engineering | FreeBSD Documentation Portal

If there's a point to be made about rapidity of development: a release engineering area will be better suited to the point.

The blurb about provision of technical support by the FreeBSD user community (highlighted in purple) will be better suited to the Support area, which already repeatedly mentions community:

– and the Web Resources option of the main Support menu leads to https://www.freebsd.org/support/webresources/.

Points of contact (higlighted in red) are normally human beings, not resources on the Internet.

Community - FreeBSD Wiki (linked from the blue area) mentions Office Hours. Office Hours (again) and more at sub-page https://wiki.freebsd.org/Community/Resources.

https://github.com/grahamperrin/freebsd-doc/blob/bug-264754/documentation/content/en/books/handbook/eresources/_index.adoc (the previewed effect of this PR) does not yet mention Office Hours, and so on …

grahamperrin · 2023-07-29T14:24:30Z

#224 (comment)

… the Web Resources option of the main Support menu leads to freebsd.org/support/webresources. …

#224 (comment)

Before making the commit open a review in phabricator please

⚙ D41096 Make clear distinction between web resources

affects Web Resources | The FreeBSD Project
relates to 260968 – Support: Web resources (page update)
changes to D41096 are expected, it will make sense to await those before (also) taking this FreeBSD Handbook: Appendix C: updates and corrections #224 to Phrabricator.

#224 (comment)

… Be concise, not repetitive: …

With the separation between web resources and resources on the Internet (attempts to cover the same subject in multiple areas):

repetition (a maintenance burden) is largely inevitable.

grahamperrin · 2023-07-29T15:52:41Z

All things considered (not least the overlaps/duplication), I strongly favour:

using the main Project site, not the Documentation Portal, for this content.

Web Resources (pictured above) can become Internet Resources.

UX

I sense that most people simply do not have eyes on this type of content as an online appendix to a long book with so many chapters and sections. It's potentially valuable content, but somewhat wasted.

Instead, have it two clicks away from the FreeBSD home page (a single click, if simply pointing at the Support menu).

As things are, ten presses of the Tab key (to select but not visit Preface):

𠄶– before a single Page Down can, or might, bring the Appendix C. Resources on the Internet into sight:

There's the second of two search fields, which certainly is good for filtering (not exactly search), however I suspect that a significant proportion of readers simply do not have eyes on this feature …

grahamperrin added 8 commits July 15, 2023 21:18

Handbook: Internet resources: printouts

98352c4

Be concise. It's 2023, the Project has transitioned to Git, I doubt that anyone needs the hint about electronic media becoming more practical than print. Remove the opening paragraph.

Handbook: Internet resources: concise, clear

0aa6089

Various improvements.

Handbook: Internet resources: Postmaster

3edbba7

In the context of FreeBSD mailing list rules, do not promote the mailto: URL for the Postmaster Team. Instead, refer to the Postmaster Team section of FreeBSD Project Administration and Management.

Handbook: Internet resources: markup

2b88dac

Remove trailing whitespace. One sentence per line.

Handbook: Internet resources: markup

6919eb6

Rationalise white space above and below a comment block.

Handbook: Internet resources: wiki, weasel

eb6b184

Remove my wiki-welated weasel words.

Handbook: Internet resources: paragraphs

631cbf3

Reduce bullet point overload. Make more use of normal paragraphs.

grahamperrin marked this pull request as ready for review July 15, 2023 22:23

grahamperrin marked this pull request as draft July 16, 2023 09:34

grahamperrin added 2 commits July 16, 2023 10:38

Handbook: Internet resources: comp.unix.misc

58e4cd5

Delist comp.unix.misc, which has nothing UNIX-related in the past eleven months.

Handbook: Internet resources: comp.unix.questions

9b36363

De-list comp.unix.questions, which had only three UNIX-related threads this year.

grahamperrin commented Jul 16, 2023

View reviewed changes

grahamperrin marked this pull request as ready for review July 16, 2023 10:22

grahamperrin added 4 commits July 29, 2023 08:52

Handbook: Internet resources: The Mail Archive

3dac16a

Add: The Mail Archive. Add: a brief comparison of listed archives (a two-message example).

Handbook: Internet resources: comparisons: order

8e84c46

The existing points about FreeBSD-provided mail archives are better placed under the new paragraph about comparisons.

Handbook: Internet resources: markup, clarity

4a5bce0

Markup: - '--' instead of '–' - <https://bugs.freebsd.org/266881> to remind me of [.filename]#/path/to/file#. Clarity: - be explicit about the text/plain nature of the non-large attachments.

Handbook: Internet resources: number the examples

1132607

Simplify, clarify: numbers 1 and 2 for the two list items.

grahamperrin commented Jul 29, 2023

View reviewed changes

grahamperrin marked this pull request as draft July 29, 2023 13:11

grahamperrin closed this Aug 20, 2023

grahamperrin deleted the bug-264754 branch August 20, 2023 11:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FreeBSD Handbook: Appendix C: updates and corrections #224

FreeBSD Handbook: Appendix C: updates and corrections #224

grahamperrin commented Jul 15, 2023 •

edited

Loading

grahamperrin Jul 16, 2023

grahamperrin Jul 16, 2023

grahamperrin Jul 16, 2023

grahamperrin Jul 16, 2023

grahamperrin Jul 16, 2023

grahamperrin Jul 16, 2023

grahamperrin Jul 16, 2023

sergio-carlavilla commented Jul 29, 2023

grahamperrin Jul 29, 2023

grahamperrin commented Jul 29, 2023

grahamperrin commented Jul 29, 2023

grahamperrin commented Jul 29, 2023


		* link:news:comp.unix[comp.unix]
		* link:news:comp.unix.questions[comp.unix.questions]

FreeBSD Handbook: Appendix C: updates and corrections #224

FreeBSD Handbook: Appendix C: updates and corrections #224

Conversation

grahamperrin commented Jul 15, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sergio-carlavilla commented Jul 29, 2023

Choose a reason for hiding this comment

grahamperrin commented Jul 29, 2023

grahamperrin commented Jul 29, 2023

grahamperrin commented Jul 29, 2023

UX

grahamperrin commented Jul 15, 2023 •

edited

Loading