a proposal for the FAQ

Mon Apr 1 05:29:30 UTC 2013

On Sun, Mar 31, 2013 at 9:25 PM, Eitan Adler <lists at eitanadler.com> wrote:

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

Since a work is continuing on documentation , I want to make a more , let's
say , radical or encompassing steps as follows :

The Handbook and the other documents is in another directory with respect
to head in SVN .

Many times , I have expressed the idea that this is causing much trouble
because the Handbook is maintained for three releases with a lot of IF
statements about releases . At present , there is NO any Handbook for the
HEAD ( or Current ) . To make or suggest any idea about the Handbook is
very difficult because it requires knowledge of at least four releases . A
person starting from Version 9.0 may  not have much idea about previous
releases . Therefore , it is very likely that there will not be much
suggestions to improve .

Another problem is manual pages : These are in ROFF , but the other
documents are in , now , XML .

I searched to find a ROFF to XML converter , but I could not find one .

My opinion is to convert ALL of them to HTML and disperse the Handbook
pages into HEAD directories where they are related with manual pages .

This conversion will eliminate the requirement of knowing three , let's say
, languages :
ROFF , XML , HTML .

It is very likely that number of such people is very small .

At the same time , it will remove necessity of generating HTML from XML .
If I am wrong , please , forgive me , because , the Handbook is in XML in
SVN , but , it is HTML in the web site .

Manual pages are ROFF in SVN , but in HTML in web site .

After such conversion , prepare appendixes to list and reference to manual
pages easily because they will also be in HTML .

When a modification patch is suggested by developers , it will contain
modifications to both manual pages and related Handbook pages .

If the same patch is applied to previous releases , also at the same time .
manuals and Handbook of that version will also be updated .

This means that   such a dispersion into the HEAD will NOT increase the
required effort , but it will reduce it actually .

Many programs in the base are displaying error messages when command line
parameters contain errors .

Since manuals will be in HTML format , instead of listing errors in spite
of the manual , by calling a routine to display manual is much more easy
and it will supply much more correct information only with ONE application .

It is NOT necessary to compress the manual pages to make them conform to
"man" program :

With respect to my understanding , "man" is a script .

When "man page" is specified to list the manual page , it may check
"page.html" : If it exists , it forks a HTML displayer with the advantage
that the referenced pages also may be displayed easily .

If "page.html" does not exist , it may use its current form .

There are some , for example , "ifconfig , mount , ..."  , programs that
when any command line parameter is not supplied , it is doing a prescribed
default behavior . All of these programs may be modified to request the
default behavior with a command line parameter .

The current scripts using these programs are in source form : They may be
easily modified .

When a release is branched , everything related to documents also will be
branched ,
and it will be very easy to modify them with the current works , because
such modifications will not be make any effect on the existing release
documentation .

In the web site , only current manual pages are accessible :

With respect to my suggestion , the documentation page in the website may
be as follows :

Handbook for Version 10.0

Handbook for Version 9.2

Handbook for Previous Versions ( 8.4 , 9.1 )

Since manual pages will be made appendixes to the Handbook , actually it is
not necessary to supply additional links to them , but their links may be
similar to the ones above .

Over time , this page will supply ALL documentation links to previous
versions , where last version is inserted top of the list .

Since the Handbook is in HTML form , it may be incorporated into a content
management system like a blog and integrated with some selected mailing
lists for some parts :

When users do not understand one point , they may enter question , or they
may suggest an improvement . In that way , the Handbook and manual pages
will be improved and updated collectively : The links to messages in
mailing lists will be appended to the Handbook pages , and over time ,
questions and information supplied in answers may be transferred to
Handbook pages .

This will make the Handbook comprehensive as much as possible , and
eliminate being outdated over time due to separate maintenance of it .

Thank you very much .

Mehmet Erol Sanliturk