Date: Sun, 31 Mar 2013 22:29:23 -0700 From: Mehmet Erol Sanliturk <m.e.sanliturk@gmail.com> To: Eitan Adler <lists@eitanadler.com> Cc: docs@freebsd.org Subject: Re: a proposal for the FAQ Message-ID: <CAOgwaMvUJ7k-eP8njER4JYMvdYNyRgmBLOTQvwhHgoUOj3Hodw@mail.gmail.com> In-Reply-To: <CAF6rxgkwV7W3FVrqmvOezsHSFwjU59yd6Ug0C0u7w3GPErtySg@mail.gmail.com> References: <CAF6rxgkwV7W3FVrqmvOezsHSFwjU59yd6Ug0C0u7w3GPErtySg@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sun, Mar 31, 2013 at 9:25 PM, Eitan Adler <lists@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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAOgwaMvUJ7k-eP8njER4JYMvdYNyRgmBLOTQvwhHgoUOj3Hodw>