With regard to the docs

D

DCH3416

I can understand the effort to move old docs to docs-archive.freebsd.org. However. Sometimes when solving issues the old docs are not only still applicable, sometimes they are better written than the latest efforts. In addition. Search engines still link to docs.freebsd.org, regardless of if it's an archive or not. Blindly dropping a user (me) onto docs.freebsd.org rather than what I was actually searching for just isn't very helpful.

And then on the docs.freebsd.org page there's a search box. Which works fine in a basic HTML browser. And when you hit enter and it just passes your query into a duckduckgo search. The problem with that is it uses javascript to inject a "site:docs.freebsd.org". That doesn't work on browsers without JS. Like I might as well have just searched using duckduckgo manually. Seems like a rather crude implementation.

Just some comments about my experience. I can appreciate the effort to "modernize" the look and feel over the past year or so. I just find it to be a bit convoluted in some aspects. The nice thing about FreeBSD is that they evolve at a much smoother pace than other *nix-like operating systems. There's a degree of polish I've come to expect that you don't see with Ubuntu and others. I think there's just a little bit of stepping backwards with the online docs.
 
Adding to that, resorting to old docs is not a solution. I can't judge whether they're "better written" (kind of doubt that in general, but sure, it might happen?), I can see that some technical decisions (like requiring javascript for full functionality) isn't liked by everyone (including myself, btw).

But still: Never rely on old/archived docs. Chances are they just don't apply any more. Yes, this happens frequently, things change all the time, so following outdated docs can be a risk.
 
For a better experience I only read the handbook from the PDF offline.
The research is handle by the PDF reader itself and the result is better.
Not a real solution, just a workaround.
 
zirias@ said:
Adding to that, resorting to old docs is not a solution. I can't judge whether they're "better written" (kind of doubt that in general, but sure, it might happen?), I can see that some technical decisions (like requiring javascript for full functionality) isn't liked by everyone (including myself, btw).

But still: Never rely on old/archived docs. Chances are they just don't apply any more. Yes, this happens frequently, things change all the time, so following outdated docs can be a risk.
Click to expand...

I needed to adjust my system's DNS settings. What came up on Google was this page: https://docs-archive.freebsd.org/doc/2.2.6-RELEASE/usr/share/doc/handbook/handbook179.html

And I know that one is particularly old.

Regardless of the level of support this method provides. What worked was editing resolv.conf and that page quickly told me how to do it.

Compared to the more modern handbook where I have to scroll through a side bar and attempt to find a solution pealing through layers of headers. Maybe it just needs to be better indexed by search engines.
 
DCH3416 said:
I needed to adjust my system's DNS settings. What came up on Google was this page: https://docs-archive.freebsd.org/doc/2.2.6-RELEASE/usr/share/doc/handbook/handbook179.html

And I know that one is particularly old.
Click to expand...
A perfect example of so many aspects missing, it's actually wrong. "The x.x.x.x and y.y.y.y addresses are those given to you by your ISP" is definitely wrong today, it doesn't work like this any more. Nameservers are dynamically communicated via ppp and when you're not using a plastic router, that means you should setup ppp(8) to update that file, which is of course explained in the handbook.

There's still the section about resolv.conf, with the added hint that dhcp also updates it. And there are other sections explaining these other mechanisms.
 
You must log in or register to reply here.
Back
Top