Date: Mon, 28 Jan 2013 04:15:32 -0800 From: Mehmet Erol Sanliturk <m.e.sanliturk@gmail.com> To: Gabor Kovesdan <gabor@freebsd.org> Cc: doc@freebsd.org Subject: Re: RFC: Dealing with version-specific docs Message-ID: <CAOgwaMuhHgA2bEBFExnS9poOg84qXDK810x60Fh47O6EiW0fXg@mail.gmail.com> In-Reply-To: <51065CFC.5090803@FreeBSD.org> References: <51065CFC.5090803@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, Jan 28, 2013 at 3:11 AM, Gabor Kovesdan <gabor@freebsd.org> wrote: > Hi, > > as you may know, the printed edition of FreeBSD Handbook is being worked. > In our current Handbook version, we have version-specific information for > different major releases, while the printed edition shall concentrate on > 9.X. We cannot just drop the parts that detail older releases since they > haven't yet reached EOL and there are people out there still using these. > So we have to deal somehow with this situation. Fortunately, DocBook > provides a mechanism, called profiling, which we could use. It would also > be beneficial for later cleanup work since finding outdated information > that has to do with unsupported releases always requires big effort. I've > made a draft about how it could be done in a practical way: > https://wiki.freebsd.org/**VersionSpecificDocs<https://wiki.freebsd.org/VersionSpecificDocs>; > > Please read it and if you have doubts, concerns or better suggestions, > please share them. > > Thanks in advance, > Gabor > ______________________________**_________________ > > Some years ago , I have suggested that the Handbook be made specific to versions : When a version is branched , it should also contain its own Handbook . The advantages of this structure is that the users will be able to concentrate only on version specific Handbook , and information about other versions will not have a confusing effect . The developers will be able to make modifications to Handbook just related to version under working . During this , there will not be any concern about breaking any information related to other versions . The users will be able to ask questions and/or make suggestions to improve the Handbook . With multiple versions contained Handbook , this is very difficult because it requires knowledge about other versions also . Especially this is a very serious problem for the new comers : These persons are starting from a version , mainly current latest release , but Handbook is also covering the older releases which they do not know . To cover multiple releases , it is necessary to introduce many IF sentences . With respect to "Expert Systems" , such IF statements requires expertise to write and to understand , and error prone , and requires much testing . The disadvantage ( as being mentioned by a mailing list member ) will be man power to manage the Handbook for different versions . Personally , I never want to enter a possible dispute with mailing list members . I think , the required effort for version specific Handbook is much less than multiple version covering Handbook , because , if any change is not applied to a prior version , which is mostly the case , its Handbook will also not be modified . If a change is applied to a version and it is copied also to prior versions , the changes to the Handbook may also be copied to their Handbooks . This will not be difficult than to modify a multiple version contained Handbook . As a result , again my primary suggestion is to make the Handbook version specific : When a version is branched , its Handbook and related other documentation also should be branched and maintained with the related version . Thank you very much . Mehmet Erol Sanliturk
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAOgwaMuhHgA2bEBFExnS9poOg84qXDK810x60Fh47O6EiW0fXg>