Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

FreeBSD Handbook Improvement Survey

marc.info

Post reply on HN
Print view View original

21–30 of 31 posts

Re: FreeBSD Handbook Improvement Survey

#21

Post by bartekrutkowski »

GekkePrutser wrote: post #18
jessermeyer wrote: post #14

Earlier quoted context omitted.

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."

That's the equivalent of "we'll get back to you". If they know and not doing anything about it they're not doing their job. 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.

You should be aware that "their job" is probably not the right term. FreeBSD is developed (mostly, technically) by volunteers and you can't make them do things you want. If you won't step up to do it, it's little unfair to demand others to do it for you.

Re: FreeBSD Handbook Improvement Survey

#22

Post by carlavilla »

blackhaz wrote: post #12
srl wrote: post #7

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 "…

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 nee…

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.

Re: FreeBSD Handbook Improvement Survey

#23

Post by GekkePrutser »

Koshkin wrote: post #20
GekkePrutser wrote: post #17

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

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

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 :)

Re: FreeBSD Handbook Improvement Survey

#24

Post by 1over137 »

vipermoney wrote: post #15
1over137 wrote: post #13

Earlier quoted context omitted.

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

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.htm... Seems to be getting worse with time too.

>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

Re: FreeBSD Handbook Improvement Survey

#25

Post by 1over137 »

GekkePrutser wrote: post #23
Koshkin wrote: post #20

Earlier quoted context omitted.

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

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 pr…

>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.

Re: FreeBSD Handbook Improvement Survey

#26

Post by GekkePrutser »

1over137 wrote: post #25
GekkePrutser wrote: post #23

Earlier quoted context omitted.

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 pr…

>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.

Ah ok fair enough, I didn't see that. Just looked for a link to click. In that case I'll participate!

Re: FreeBSD Handbook Improvement Survey

#27

Post by chalst »

GekkePrutser wrote: post #19
Decabytes wrote: post #8

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?

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…

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.

Re: FreeBSD Handbook Improvement Survey

#28

Post by thijsvandien »

hereforphone wrote: post #10
srl wrote: post #7

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 "…

Interesting use of slashes

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.

Re: FreeBSD Handbook Improvement Survey

#29

Post by throwawaybsd »

Koshkin wrote: post #20
GekkePrutser wrote: post #17

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

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

No post body was provided.

Re: FreeBSD Handbook Improvement Survey

#30

Post by carlavilla »

carlavilla wrote: post #22
blackhaz wrote: post #12

Earlier quoted context omitted.

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 nee…

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.

Sorry for the delay, I'm gonna answer my previous post :)

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.

Post reply on HN