Hacker News Reader

Comment by dbolgheroni | Hacker News Reader

From the blog: "I write this as the FreeBSD Handbook does not cover all that information in the 11.13. Power and Resource Management chapter. The FreeBSD on Laptops article part 4. Power Management is from the ancient times of FreeBSD 10.1-RELEASE. There is some information on the FreeBSD Wiki page but parts of it are outdated."

The best way to help FreeBSD (or any open source projects in general) is to submit diffs to the project documentation itself, than to have lots of documentation scattered among blogs (which will soon become outdated also).

The project benefits by having up-to-date documentation, the users benefit by having a single source of truth and a lot of questions in the mailing lists are saved by users not following documentation which probably are no longer relevant.

View on HN

When I was playing with FreeBSD a lot in late 2017/early 2018, I had a ton of time wasted following outdated chapters in the Handbook. It became very frustrating once I found the 7th or 8th "this part of the Handbook is outdated" post on the FreeBSD forums. Kinda funny, because the Handbook is often touted as something which is supposed to make it very welcoming to beginners.

The FreeBSD Handbook is generally very well written but for parts that change often or that are 'less popular' it could be managed little better.

IPSEC is a good example where its lacking. Its in desperate need to be updated with modern config examples and documentation, especially with newer keying daemons like FreeSWAN. Maybe the time gods will be kind to me in December and I can find cycles to make a start at it rather than moan from the sidelines :)

Back when I started using FreeBSD in the 4.x days the handbook was an extremely valuable and useful resource. For many years I touted it as a good advantage of FreeBSD over Linux, whose documentation was (and to some degree, still is) quite poor and scattered over many places.

I haven't used FreeBSD in quite a few years, but I'm sad to hear it's no longer what it was :-(

Looking at the source it looks like they went from the obscure SGML to ... some obscure XML. The entire thing looks horrible and a pain to edit, so I'm not surprised that few people contribute (including the OP).

It's written in DocBook, which is hardly obscure.

No, but it is horribly verbose and a pain to work with. I personally find the flow of writing to be constantly interrupted with the demand to mark everything up just so, and for very technical documents with a lot of markup, the markup can dwarf the content several times over!

While they are less powerful, markdown, restructured text and other simpler markup languages are much more productive to work with. They are easier for beginners to understand, and the markup is sufficiently lightweight for most of the common cases that it doesn't interrupt your train of thought while trying to think about how to best describe complex technical details.

An alternative to retext is Mallard. It's pretty easy to use, see http://projectmallard.org/. It's used within GNOME for the documentation.

Thanks, I took a quick look. However, it appears to be XML-based markup not too different from HTML or DocBook. So I don't see this having the benefits which lightweight markup provides. It has all of the same disadvantages of HTML and DocBook in terms of the markup verbosity from what I can tell.

Which isn't to say it's not very good at what it does, just that I can't see a compelling difference over DocBook or HTML.

The nice thing about DocBook is that, because of how strictly structured it is, there are visual editors for it that provide experience far superior to anything that can be had with Markdown etc, especially for large quantities of documentation. I would dare say that it's also easier for beginners that way, too.

Long time no see :)

Thanks for comment. I generally agree with you, that I should now check what is available in the Handbook and submit patches to make it better but I have very unpleasant memory from the past.

There was time when VirtualBox was not available on FreeBSD, no one even thought about writing Bhyve and QEMU was only 'virtualization' option on FreeBSD (with KQEMU accelerator module).

As I used FreeBSD I even made a howto - HOWTO: QEMU on FreeBSD - still available here: https://forums.freebsd.org/threads/howto-qemu-on-freebsd.175...

... and someone suggested just that, to add my thoughts/changes to the FreeBSD Handbook.

... so I did sit down and rewrite entire 'Virtualization Chapter' in HTML, still available here: http://www.strony.toya.net.pl/~vermaden/FreeBSD-Handbook-Vir...

... and no one done anything with it.

It was not merged, not a single bit from it was merged into the FreeBSD Handbook.

When I asked why I got response that maybe if it was in the correct format (I do not remember which documentation framework FreeBSD used back then) some parts would be used but as its in HTML no one will even 'waste' time merging it. I did the most 'hard' part which is creating the valuable content, formatting is secondary thing for me, but it was not for them.

Since then I do not bother about FreeBSD Handbook. I still use it from time to time thou. I would not have anything against even if someone would put my entire article there without any changes, that would serve a lot of people, but if someone will do it, that I do not know.

Regards.

Without meaning to offend or diminish the work you did, I want to defend the FreeBSD project here.

Consider the code version of what you linked above. Imagine submitting a patch in the form of an HTML post on a private website (wrong format), in poor and non-idiomatic style (both for the project and the language itself), full of typos and grammatical errors (bugs?), with the author themselves professing that it's "nowhere near finished".

If someone submitted a patch to any serious open-source project in this form, they'd tell you in one way or another to come back when your patch was finished and was written in accordance with the standards of the project. You haven't done most of the hard part at all: you're complaining about their lack of gratitude for the beautiful lamb dinner you've cooked for them, but really all you've done is dump a lamb on their doorstep and expected them to shepherd it, slaughter it, and prepare it.

(there's a flip-side to this: while the original comment you're replying to is right that (properly) contributing to the official documentation is the best way to support it and better than writing up a blog post, it also presumes that we all have the time or energy for that kind of commitment, which is much greater than that for just writing up a blog post.)

It was long time ago and and today it would probably look better but still zero response is not a good sign either.

Volunteer time often means that if something isn't immediately actionable, or actionable with minimum effort, it gets ignored, and then it gets forgotten. It's not malicious, it's just the reality of things.

If you had obtained the handbook from version control, and added this as a new file using the markup language in use, made sure it built without warnings or errors, proofread the HTML and PDF output, and then sent that in as a patch, it would have been mergeable with no effort other than a brief review.

If the people reviewing it also had to completely rewrite it in the correct markup language, and they are not domain experts in the material it is covering, then you've basically given them a task which is hugely demanding upon their time.

I've had several experiences of this. Sometimes it pays to pull all the stops out and spoonfeed the recipients with something which is as perfect as it can be, and they have no reason not to merge it. It takes a lot more time on the part of the submitter, but that's time you've saved the reviewer, by giving them a finished article. This can greatly improve the chances of success, by removing obstacles which would hinder it.

Thanks, I will try that path then.

Just as random someone who likes reading your posts, maybe there's a third way: An appendix in handbook that links to blogs like yours.

I see that there already is "an aggregation feed of dozens of blogs" linking to planet.freebsd.org which does not respond :)

Good idea.

There is also FreeBSD Community Resources wiki page - https://wiki.freebsd.org/Community/Resources - which contains links to such blogs and resources.

In case of documentation PR's the doc team is openly accepting properly written (technically, grammatically and so on) plain text documents and takes the burden of writing the proper docxml patch on them, simply get in touch with them vi Problem Report or IRC or mailing list :)

Reply on news.ycombinator.com