FreeBSD Handbook Improvement Survey

https://marc.info/?l=freebsd-announce&m=165016689418229&w=2

74 28 4 years ago

johnklos• 4 years ago

Isn't it nice when good documentation is treated as more than an afterthought? This is good to see :)

vipermoney2• 4 years ago

Judging by the massive amount of unfixed bug reports linked in this email, doesn't it seem like documentation has been an afterthought for them for a long time?

Does anyone have a comparison for OpenBSD or NetBSD's documentation having outdated or incorrect info?

the_only_law• 4 years ago

NetBSD documentation is just straight up missing sometimes. iirc a lot of kernel interfaces are both missing documentation and are different than other BSDs. You either need dig through the source or ask for help.

1over1373• 4 years ago

Is that really such a massive number of bug reports, for a project as large as FreeBSD? I'm not convinced.

fegu• 4 years ago

I have a FreeBSD certification gained from an exam at EuroBSDCon some years (many years actually) ago. FreeBSD is great, and we still run it at work. Great docs is part of the reason we like it.

(Btw this page is extremely annoying to read on mobile. I get that we like the no frills console 1337 vibes, but usability is perhaps even higher?)

erk__• 4 years ago

The official archive seems to be a bit better https://lists.freebsd.org/archives/freebsd-announce/2022-Apr...

srl• 4 years ago

I'm baffled. Is there some broader context that makes this make sense? From what I can tell, this fellow (the one sending the email) is being paid money to develop priorities for updating the FreeBSD handbook. His response is to send an email to the /announcement/ mailing list, with a list of all the relevant bug reports he could find, asking others to do his job for him?

A reasonable survey to send around might be "how often do you use the FreeBSD docs?" "How often do you notice errors in section 1? Section 2? Section 3?" That's not what this is. It's "here's a specific error, and I'm gonna run a /poll/ to figure out what the priority on fixing it is".

Even ignoring the "that's why we hired /you/" component---this must be a singularly ineffective way to gain reliable information. Very few people are going to reply (because each of the ~100 questions is rather technical!). The responses are therefore going to be self-selected to... I don't know, whoever has the time and will to waste on this.

hereforphone• 4 years ago

Interesting use of slashes

thijsvandien• 4 years ago

This is a common way of expressing italics in plain text. Not that it's needed on HN, because here one can use asterisks and get actual italics.

blackhaz2• 4 years ago

What is also baffling is the new state of the FreeBSD Handbook. I am a newcomer, so my voice probably doesn't matter much - I've been running FreeBSD since 9 as my primary desktop. The Handbook was a neat collection of formatted HTML pages. The contents section was where you'd expect it - at the top. Typography, code colors, vertical and horizontal indents were all well-thought - it was easy to find the stuff you need fast. The person(s) who made it were concentrated on delivering information.

The new Handbook is really bad. The contents in split HTMLs is on the left, but then there is another contents section on the right. There contents in single HTML is on the right (why?) Typography is a weak mix of serif and sans-serif and italics in illogical places. Interline spacing is bad - the feeling is that instead of a reference book we are now looking at a poorly designed advertisemsent brochure, but still structured as a book. Chapters, sections and subsections are poorly demarcated - you can't tell when things end and new things begin. Horizontal and vertical indents separating coherent blocks of text are all broken - you simply can't easily find the information you need.

Maybe I'm an old fart, and I like Beastie more than this soul-less flat demon, but I think the new person in charge of the Handbook is concentrated on "design" more than on the content. Sorry for the off-topic, fellas. Just needed to get it out.

jessermeyer• 4 years ago

The discord community seems acutely aware of this. When I first became acquainted with the system last year I made an effort to document my confusion when hitting roadblocks after reading the handbook to them, and most of them came down to usability issues with the implementation of the pages. The response was always the same "we know, and thanks for the report."

carlavilla2• 4 years ago

Hi,

Thanks for your feedback. I’m the responsible of the new design. Can you please contact with me? I’m looking to improve the design.

carlavilla@FreeBSD.org

This night I’ll update the post with a brief explanation.

Decabytes• 4 years ago

How much overlap is there between OpenBSD, FreeBSD, and NetBSD? Like can I use the FreeBSD one to learn how to use the other BSDs?

protomyth• 4 years ago

In a general sense, and a lot of commands are the same, but they are very different for a lot of stuff.

Compare https://docs.freebsd.org/en/books/handbook/ to https://www.openbsd.org/faq/index.html and you can see the large differences.

spijdar• 4 years ago

This isn't a direct answer, but I think it'll help understand their relationship/how similar they're likely to be.

All of the above are descendants of an OS that Berkeley released called "BSD". BSD only ran on PDP-11s, and then, VAX minicomputers, with a few proprietary ports to expensive workstations (SunOS, Sony NEWS, etc).

The code was a "distribution" of modifications on top of AT&T UNIX, so it couldn't be freely shared to people without a UNIX license. So the developers released part of their own code separately, the most important released called "Net/2".

Two alumni of Berkeley worked on expanding the free distribution to be 1) a full OS and 2) run on regular Intel 80386 PC clones. This was called "386BSD".

The last "official" BSD was 4.4BSD, which had the goal of wider software and hardware compatibility, adding support for a wide range of computers.

Disagreements with the developers of 386BSD led to a fork, eventually named "FreeBSD" (as in Free86BSD, I think). They continued the goal of a PC compatible BSD.

Another group took 386BSD and reintegrated 4.4BSD code back in, continuing the Berkeley goal of "wide hardware compatibility", which became NetBSD. "Internal disagreements" eventually led to one of the core developers leaving to make OpenBSD, which differed in that the development source repository was always publicly available (at the time NetBSD only released source for a full release, only team members could pull from the CVS repo).

All that to say, FreeBSD is sort of its own thing, with NetBSD and OpenBSD sharing much more. They've all diverged quite a bit, but have simultaneously shared a lot of code (especially things like device drivers).

So, broadly speaking, using any BSD will make you "familiar with BSD", but they really are quite distinct at this point.

GekkePrutser5• 4 years ago

Not really. They have the same origins but totally different focus and have been apart for so long that they are substantially different.

Though they borrow stuff from each other. And even Linux does (OpenSSH for example comes from OpenBSD).

In general FreeBSD is a great allrounder with up to date packages. OpenBSD is very focused on security and it's pretty minimalist as a result though you can install what you want. NetBSD strives to support as many hardware platforms as possible so it's a good choice for that weird old server you found on ebay. They had more similar goals in the past but this is how they've diversified (at least how I see it!)

Besides these focus differences there's also some personalities behind the different BSDs that make Linus look like a kitten :) So that tends to influence people's OS of choice as well. I don't want to get involved in that but I wanted to give the heads-up because it will come up in discussions once you start looking into the BSDs.

chalst• 4 years ago

I kind of think NetBSD doesn't so much 'strive' to support many platforms as try to pursue simplicity of implementation and so be easy to port. Linux supports a lot of platforms, but porting Linux is a much more heroic effort.

The NetBSD codebase is nice for studying operating system concepts.

GekkePrutser5• 4 years ago

Too bad that this happens on the mailing list. Having a web survey would be much more conducive to mass participation.

Koshkin• 4 years ago

Conducive to mass “BSD is dying” trolling, BSD vs. Linux flamewar and such.

GekkePrutser5• 4 years ago

Not really. I am a daily user of FreeBSD, it is my main driver.

However I am not on the mailing list. I hate mailing lists, they clutter my mailbox and I consider them an inefficient way of discussing. I prefer things like IRC that are more direct. And anonymous, which is also important these days. Signing up for a public mailing list like this is inviting a wave of spam. Sure I can make a spare google mail box or protonmail or whatever but that makes it even harder to access the mailing list.

I would participate in this survey if I didn't have to sign up for the mailing list. So it is deterring at least one daily FreeBSD user as well :)

FreeBSD Handbook Improvement Survey

Related Stories