Hacker News Reader

Comment by AndrewBissell | Hacker News Reader

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.

View on HN

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

Reply on news.ycombinator.com