5 ms·

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 Lap

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 8y ago
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.
- vermaden 8y ago
  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.
  - mdtancsa 8y ago
    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 :)
- Carpetsmoker 8y ago
  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 8y ago
    It's written in DocBook, which is hardly obscure.
    - rleigh 8y ago
      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 8y ago
        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 8y ago
        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.
vermaden 8y ago
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/ 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-Virtualization.htm 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.
- wk_end 8y ago
  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.)

AndrewBissell 8y ago

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.

vermaden 8y ago
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.
- mdtancsa 8y ago
  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 :)
Carpetsmoker 8y ago
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 8y ago
  It's written in DocBook, which is hardly obscure.
  - rleigh 8y ago
    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 8y ago
      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 8y ago
        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.

vermaden 8y ago

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/ 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-Virtualization.htm 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.

wk_end 8y ago
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.)