a proposal for the FAQ

Eitan Adler lists at eitanadler.com
Mon Apr 1 04:25:50 UTC 2013


Hi all,

Over the past several months I have been working on a project called
ThwackAFAQ.  For those who don't know this project has been to review,
edit, and rewrite the FAQ to be relevant to the modern day.
I've removed references to hardware that hasn't been sold in over 10
years or to software features that reached their EoL in FreeBSD 2.x.
At this date I feel the project has reached a level of maturity such
that it makes sense to write this email:

I propose that we merge the handbook into the FAQ.

While they both cover the same material the handbook source is over
83892 lines of XML while the FAQ is now at a measly 8242 lines.
Further the FAQ is in bite sized chunks while the FAQ requires lots of
tedious reading.  Translators currently have issues keeping up with
the pace of changes in both books, and must translate the same basic
content twice.  If only we could have one clear and canonical source
for translators to work with.

Sure there are some topics not covered in the same depth in the FAQ
but many Linux distributions solve this in a very nice way: distribute
the details and extraneous items to bloggers and tip writers.  This
releases us, the doc team, from all the extra work of writing and fact
checking things that will no longer be true in the next version of
FreeBSD.  Not only that but it even generates more content for the
front page where we publish articles written about the operating
system.

Over the next few weeks (as soon as the doc slush ends) I intend to
move the last few remaining portions of the handbook into the FAQ and
commit the removal of the handbook once and for all.

-- 
Eitan Adler


More information about the freebsd-doc mailing list