From owner-freebsd-doc@FreeBSD.ORG Mon Jan 28 12:15:33 2013 Return-Path: Delivered-To: doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id CBC4272D; Mon, 28 Jan 2013 12:15:33 +0000 (UTC) (envelope-from m.e.sanliturk@gmail.com) Received: from mail-ia0-x230.google.com (ia-in-x0230.1e100.net [IPv6:2607:f8b0:4001:c02::230]) by mx1.freebsd.org (Postfix) with ESMTP id 96A4363C; Mon, 28 Jan 2013 12:15:33 +0000 (UTC) Received: by mail-ia0-f176.google.com with SMTP id i18so4000758iac.7 for ; Mon, 28 Jan 2013 04:15:33 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:x-received:in-reply-to:references:date:message-id :subject:from:to:cc:content-type; bh=j2/YGDsdRPE8/W5YGsQ+65lpa7rkro/unjY4rPsbhWE=; b=uwJlSSvmGo7dz7ylu89GHr7JiMDm9XRMktS/ao6Mg2bmuBNI+PsNcJ30LKU3Mzar2Q FFlwQECcM963P5W3QVoJZwmbrGqIvcztcOQdRTGk0GkOGCIj9kfATD4GxQGGaARQmRBI nI5itAKCk8RZve+kQy1RVWF2gdq1lCT3JGJz9qNAPKPQYGnV+faRok9ftHJlr+pXV9ds 29g/NV1xOm/8YNT0+8mhHw5gyV0CB+uWWelk2ruhqgmK2lqvmLiYSnin/f33fa7AFZw1 WzhzY9CiRg5qk9NxNvTQeXHAbOAFmxKAQp7NfjFyNZeEFS5e9wwqI66gmHjyxfsRGwGn KzuQ== MIME-Version: 1.0 X-Received: by 10.50.57.234 with SMTP id l10mr4803384igq.18.1359375333138; Mon, 28 Jan 2013 04:15:33 -0800 (PST) Received: by 10.42.118.70 with HTTP; Mon, 28 Jan 2013 04:15:32 -0800 (PST) In-Reply-To: <51065CFC.5090803@FreeBSD.org> References: <51065CFC.5090803@FreeBSD.org> Date: Mon, 28 Jan 2013 04:15:32 -0800 Message-ID: Subject: Re: RFC: Dealing with version-specific docs From: Mehmet Erol Sanliturk To: Gabor Kovesdan Content-Type: text/plain; charset=UTF-8 X-Content-Filtered-By: Mailman/MimeDel 2.1.14 Cc: doc@freebsd.org X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 28 Jan 2013 12:15:33 -0000 On Mon, Jan 28, 2013 at 3:11 AM, Gabor Kovesdan 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 > > 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