5 ms·

FreeBSD Handbook Improvement Survey

johnklos 4y ago
Isn't it nice when good documentation is treated as more than an afterthought? This is good to see :)
- vipermoney 4y 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 4y 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.
  - 1over137 4y ago
    Is that really such a massive number of bug reports, for a project as large as FreeBSD? I'm not convinced.
    - vipermoney 4y ago
      Perhaps it's not as large as you think, relatively speaking. If we take a look at bugs.freebsd.org, it seems that many bug reports are opened and left to rot for years. The documentation section of the tracker is no exception. https://bugs.freebsd.org/bugzilla/page.cgi?id=showreport.html&type=total_open_bugs_over_time https://bugs.freebsd.org/bugzilla/page.cgi?id=showreport.htm... Seems to be getting worse with time too.
      - 1over137 4y ago
        >many bug reports are opened and left to rot for years Yup. This is common for many project, like llvm: https://github.com/llvm/llvm-project/issues https://github.com/llvm/llvm-project/issues
fegu 4y 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__ 4y ago
  The official archive seems to be a bit better https://lists.freebsd.org/archives/freebsd-announce/2022-April/000029.html https://lists.freebsd.org/archives/freebsd-announce/2022-Apr...
Decabytes 4y 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 4y 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/ https://docs.freebsd.org/en/books/handbook/ to https://www.openbsd.org/faq/index.html https://www.openbsd.org/faq/index.html and you can see the large differences.
- spijdar 4y 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.
- 4y ago
srl 4y 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.
- deleted 4y ago
  [deleted]
- hereforphone 4y ago
  Interesting use of slashes
  - thijsvandien 4y 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.
- blackhaz 4y 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.
GekkePrutser 4y ago
Too bad that this happens on the mailing list. Having a web survey would be much more conducive to mass participation.
- Koshkin 4y ago
  Conducive to mass “BSD is dying” trolling, BSD vs. Linux flamewar and such.
  - GekkePrutser 4y 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 :)
    - 1over137 4y ago
      >I would participate in this survey if I didn't have to sign up for the mailing list. You don't. In fact the instructions ask specifically that you don't reply to the list. To participate you just need to email that poster.
      - GekkePrutser 4y ago
        Ah ok fair enough, I didn't see that. Just looked for a link to click. In that case I'll participate!
  - throwawaybsd 4y ago

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

vipermoney 4y 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 4y 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.
- 1over137 4y ago
  Is that really such a massive number of bug reports, for a project as large as FreeBSD? I'm not convinced.
  - vipermoney 4y ago
    Perhaps it's not as large as you think, relatively speaking. If we take a look at bugs.freebsd.org, it seems that many bug reports are opened and left to rot for years. The documentation section of the tracker is no exception. https://bugs.freebsd.org/bugzilla/page.cgi?id=showreport.html&type=total_open_bugs_over_time https://bugs.freebsd.org/bugzilla/page.cgi?id=showreport.htm... Seems to be getting worse with time too.
    - 1over137 4y ago
      >many bug reports are opened and left to rot for years Yup. This is common for many project, like llvm: https://github.com/llvm/llvm-project/issues https://github.com/llvm/llvm-project/issues

fegu 4y 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__ 4y ago
The official archive seems to be a bit better https://lists.freebsd.org/archives/freebsd-announce/2022-April/000029.html https://lists.freebsd.org/archives/freebsd-announce/2022-Apr...

Decabytes 4y 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 4y 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/ https://docs.freebsd.org/en/books/handbook/ to https://www.openbsd.org/faq/index.html https://www.openbsd.org/faq/index.html and you can see the large differences.
spijdar 4y 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.
4y ago

srl 4y 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.

deleted 4y ago
[deleted]
hereforphone 4y ago
Interesting use of slashes
- thijsvandien 4y 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.
blackhaz 4y 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.

GekkePrutser 4y ago

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

Koshkin 4y ago
Conducive to mass “BSD is dying” trolling, BSD vs. Linux flamewar and such.
- GekkePrutser 4y 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 :)
  - 1over137 4y ago
    >I would participate in this survey if I didn't have to sign up for the mailing list. You don't. In fact the instructions ask specifically that you don't reply to the list. To participate you just need to email that poster.
    - GekkePrutser 4y ago
      Ah ok fair enough, I didn't see that. Just looked for a link to click. In that case I'll participate!
- throwawaybsd 4y ago