FreeBSD Handbook Improvement Survey
marc.info
marc.info
Does anyone have a comparison for OpenBSD or NetBSD's documentation having outdated or incorrect info?
https://bugs.freebsd.org/bugzilla/page.cgi?id=showreport.htm...
Seems to be getting worse with time too.
Yup. This is common for many project, like llvm: https://github.com/llvm/llvm-project/issues
(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?)
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.
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.
That's not so bad for a free project but if they pay someone to do it that sounds like a bigger problem.
Edit: In reply to the comment below which I can't reply to: Someone else mentioned the person doing the server was being paid for the work on the handbook.
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.
First of all, thanks for your feedback. I'm gonna try to answer all of your questions. I also got some emails about this and I'll ping you requesting your opinion about some changes I planned to improve the usability. Again, thanks for your feedback and to get in touch with me.
First of all, I didn't notice this complaint in Discord. I'm in the FreeBSD forums, the FreeBSD mailing list, IRC, and some telegram channels, but I wasn't in Discord. Right now I am in Discord. The truth is that there's plenty of ways to communicate with us (the developers) and we cannot stay in touch in every place, sorry. But I was informed about the usability problems in the FreeBSD Forums. Right now I'm working in a way to hide the book menu and the table of contents menu. If it's taken me so long to get to work on these problems it's because I do this in my spare time. Sometimes I have more free time and sometimes not. This last month I haven't had any free time because we're developing a new tool at my work and this takes a lot of time. I'm the main architect and you know... (of course using only FreeBSD ;)
Secondly, nobody paid me for the new design and nobody paid me to migrate the documentation to Hugo/AsciiDoctor. I've made it because I'm a FreeBSD user and I thought this is some kind of "contribute to something that I'm using in my personal laptop and at my job for free". So basically, I made this for free. And I'm really proud to belong to the FreeBSD Community and to dedicate my free time to this operating system.
Apart from that, we're also working on a new design for the main page and also a new page for the manual pages and for the ports.
And right now the regarding questions about the new design.
* The left side of the page: What you can see on the left side are all the chapters of the book. In the old design, if you're for example in the second chapter and you want to go to the ninth chapter you have two options. First, go to the index (one navigation in the browser) and find the ninth chapter in the index and click to this chapter (another navigation in the browser). Right now you have all the chapters on the left side. I think this is an improvement. I am working on a search tool to search in the chapter titles and filter them.
* The right side of the page: What you can see on the right side of the page it's the Table of Contents of the chapter. In the old design, if you are in the middle of the page and you want to navigate to another section of this same page, you have two options. First, go to the top of the page to locate the Table of Contents and click on the desired chapted. Second, use the scroll to navigate to the desired section. Right now you have all the chapters always on your screen. (As I said, I am working on a way to hide this ToC). Apart from that, on the right side you can see an easy way to download the book or the article in PDF (we're working in the epub format). You don't need to navigate to the FreeBSD FTP, etc. You have the PDF in one click and in an easy way to get it. And if you want to edit the page because you found an error. You can press the link and modify the page. In this way we want to encourage people to contribute to FreeBSD.
> Typography is a weak mix of serif and sans-serif and italics in illogical places.
About the font. All the portal is using the Inter font and mono font for the command examples. In the old design it's true that we're not using Inter but we're using the same font for the commands examples.
Can you please share a place in which you think italic should not be used? Maybe it was a mistake in the conversion to AsciiDoc.
I know that changes are hard. In the end we're humans and we like what we are accustomed to. If some of you have been using FreeBSD since version 9 and reading the manual for 7 or 8 years it is normal that this change is difficult.
And about the topic of this thread :)
I'm really happy to see this kind of initiative. It is very good that someone lifts the rug and brings out all the improvements that can be done in documentation. And it's a really good initiative.
If some of you want to collaborate with the documentation. Please, don't hesitate to contact me by email.
Bye and thanks again for your feedback. I'll answer the emails ASAP.
Thanks for reaching out. Not sure if we should continue here or via e-mail. If the new design was approved by the FreeBSD community then what say do I really have in all this? I am conservative. I am sure many will disagree with me. I type this on a 101-key Austin PC/AT keyboard. I think iPhone 4 was the best of all, that Mac OS X peaked at Snow Leopard, Apple is going backwards in terms of UI, and I'd rather see computer screens going back to 4:3. I like old music. I hate touch screens and non-tactile switches in cars with a passion. I am convinced that many modern design decisions are actually harmful. I'd rather live with as little design as possible.
Sorry, back to the new Handbook...
1. I don't like that contents are separated in two panes on both sides of the main content. I think this is a harmful decision. First, you are left with space too narrow for the main content. This reminds me of 2010s web magazine/news sites designs where 50% of the screen is wasted for ads and the main content is just a single narrow column of text. Next step here is that this narrow column forces you to split your text into shorter and shorter paragraphs to remain readable, until you realize each sentence ends up on its own paragraph like we're serving people with attention disorder. I don't think this is the right format for a book. We are not trying to grab attention here. Design should disappear and let user do his stuff.
2. Table of contents should be at one place. It's really strange that you click on a topic in the left pane, and then an update happens on the right pane all the way across the main text, but the context for both panes is the same - providing user with a ToC. Also, the right pane is called "Table of Contents" but it's ToC for the current chapter only, not for the entire book. Then you have "Book chapters" on the left - is this the full ToC? (Should "chapters" be capitalized?) I very much prefer the old system with just one ToC at the beginning of the book, as in all the books we read, or ToCs appearing at the beginning of the chapters. They shouldn't be all the time on the screen, pretty much like you don't have a ToC hanging out of your reference book all the time while you're reading it. It's not a brochure!
3. I don't like complex CSS getting involved at all. The less CSS/JS, the better. I appreciated Handbook being a simple HTML. I hate when web pages begin to hide elements, or things begin to slide, fold and unfold, text moving on the screen, and so on. I am here to read the book, learn things and do my stuff in the other window. Please make everything as static as possible. The less the UI interferes with my reading process, the better. This includes the two ToC panes that are scrollable. It's like reading a book with some kind of inserts. Do we really need the "top" button at the bottom of the page? Why would want to clutter our screen with that button if there's a Home button on the keyboard? Are you optimizing for tablets and phones? But most mobile devices can scroll back to the top, at least iOS can. We don't need another element here.
4. Interline spacing is not for a book - too much space between lines. Is that 1.15 or 1.2? I'd go back to the old format. The font is gray - why are we loosing contrast, what for? The font doesn't match the web site. Not sure which "portal" you are referring to. The hyperlinks are not underlined, why? I also think there should be a little vertical indent between paragraphs.
5. It will take me a really long time to sip through all the italics. Quick example: paragraph 2.2. Architectures are in bold italics. I can understand bold here, but why italics? Although I'd make bold a little less pronounced. It really screams.
6. The code snippet background color, e.g. paragraph 4.3.1. It was a pleasant almond in the old book. Now the background is black. You are inverting from grey text on white all the way to white text on black. My eyes are crying - why? I guess this was a simulation of a terminal window, but not all terminals are black. This inversion breaks the coherence.
7. Chapter/section/subseciton titles were dark red in the old book, which helped to "unglue" different subjects vertically, especially in a single HTML. Now they're all grey. There's a barely visible (actually to the point of irritation!) horizontal underlining in chapter titles, but as it's an underline it actually contributes to the vertical clutter.
8. Filenames were green in the old book, and now they are grey, but not only that - they're extremely bold. This one is controversial, but I really dislike jumping to that much bold in the main content - I think it interferes with attention and makes the text look incoherent, as bolded out filenames stand out from the rest of the text. With that much bold, and especially with main text being a subtle grey, filenames really grab too much attention and even compete with chapter titles.
9. Warning and note section titles are in the serif font. Why suddenly serif here? Don't get me wrong, I really like serif. I would switch FreeBSD all the way back to serif, I think it was really cool, different and, most important, pleasant for the eyes and easy to read. It showed that FreeBSD is not always chasing for the bleeding edge and that UNIX traditions are valued. But if we are switching everything to sans serif now so badly, then why this sudden move? We need a typographer here.
Compare https://docs.freebsd.org/en/books/handbook/ to https://www.openbsd.org/faq/index.html and you can see the large differences.
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.
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.
The NetBSD codebase is nice for studying operating system concepts.
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 :)
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.