From owner-freebsd-doc@FreeBSD.ORG Tue May 27 21:17:59 2008 Return-Path: Delivered-To: freebsd-doc@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id AA8071065676 for ; Tue, 27 May 2008 21:17:59 +0000 (UTC) (envelope-from sonicy@otenet.gr) Received: from rosebud.otenet.gr (rosebud.otenet.gr [195.170.0.94]) by mx1.freebsd.org (Postfix) with ESMTP id 30B278FC19 for ; Tue, 27 May 2008 21:17:58 +0000 (UTC) (envelope-from sonicy@otenet.gr) Received: from aquarius.dyndns.org (athedsl-08121.home.otenet.gr [87.202.31.247]) by rosebud.otenet.gr (8.13.8/8.13.8/Debian-3) with ESMTP id m4RLHuMm017848; Wed, 28 May 2008 00:17:57 +0300 Message-ID: <483C7AD4.5090409@otenet.gr> Date: Wed, 28 May 2008 00:19:16 +0300 From: Manolis Kiagias User-Agent: Thunderbird 2.0.0.14 (X11/20080501) MIME-Version: 1.0 To: Hiroki Sato References: <483B3E98.6040804@otenet.gr> <483B92D1.4040500@FreeBSD.org> <483C6E04.3070804@otenet.gr> <20080528.060009.127260270.hrs@allbsd.org> In-Reply-To: <20080528.060009.127260270.hrs@allbsd.org> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Cc: freebsd-doc@FreeBSD.org Subject: Re: Wiki style FAQ proposal X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 27 May 2008 21:17:59 -0000 Hiroki Sato wrote: > Manolis Kiagias wrote > in <483C6E04.3070804@otenet.gr>: > > so> - Create a wiki style FAQ (while still maintaining the current version of the FAQ) with a possible future plan to limit the original SGML FAQ to questions related to the way the Project works, rather than technical stuff. > so> - Maintain the current FAQ as is, and also create a wiki that will serve for the most up-to-date technical questions. Periodically, these could also be used to update the SGML version of the FAQ, or (if possible) the wiki could be converted in a way to static content so it becomes re-distributable. > so> > so> We believe experimenting with a wiki style FAQ (regardless of what is decided about the SGML FAQ) is a good idea, since more people will be able to get involved and the information will be much more current and useful. We also realize there maybe several drawbacks to it: 1) Not really distributable (as mentioned above) 2) Good administration will be needed so the organization of categories and content does not become 'chaotic' > so> > so> In the light of the above, we would like to hear the community's and the committers' ideas and proposals on the above plans. > > I agree that the current FAQ in SGML includes too much stale > information and maintaining it is hard, and we definitely need a way > to improve it. My thought is the following: > > - As you pointed out maintaining wiki as a good shape is time > consuming than many expected. Using wiki as a working place is not > bad, but I am not for using it as the primary place which holds the > FAQ. > > - For making maintenance of the current FAQ easier, the following > would be effective I think: > > a) Separate the current SGML source file into small SGML/XML files > based on category. Also, we may need to add more "category tag" > (something used in a blog entry, for example) to categorize each > item flexibly. > > b) Add "age after the last review" for each item to make it > possible to review too old information later. Periodic review > should be scheduled in a way like "all items have to be younger > than 1 year old". SGML/XML framework can handle this sort of > information processing easily. > > c) Add a capability of keeping view count of each item if possible. > We need to know which item is most frequently referred. > > Do you have more specific idea for using wiki for drafting work of > FAQ entries? I think there is no problem if we maintain the static > content and the wiki can encourage people to update. > > -- > | Hiroki SATO > Gabor Pali actually had the nice idea that the wiki could have two areas, like a "CURRENT" and "STABLE" branch. More people could contribute in the current branch, and then the maintainer(s) could move what would be considered more valuable content to the 'stable' branch. This would also mean there is enough quality control and the whole thing does not become disorganized. I don't have any specific technical solution in mind for transferring content from the wiki to the sgml FAQ. I suppose we could have some maintainers that would periodically check what changed in the 'stable' version and update the static FAQ. Decision of what should go in the static FAQ could be based on several factors. If you ask me, I would consider best to not include very fast changing information in the static FAQ. I would, for example, leave the entries that deal with very specific hardware troubleshooting (i.e. machine foo will not load FreeBSD 6.X) to the wiki, as these get outdated fast as hardware becomes obsolete.