
The Power to Serve – FreeBSD Power Management - vermaden
https://vermaden.wordpress.com/2018/11/28/the-power-to-serve-freebsd-power-management/
======
dbolgheroni
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.

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

~~~
Carpetsmoker
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).

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

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

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

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

