From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) by finch.gentoo.org (Postfix) with ESMTP id 2CA55138222 for ; Thu, 5 May 2016 11:06:32 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id A963221C11C; Thu, 5 May 2016 11:06:28 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 15C6521C012 for ; Thu, 5 May 2016 11:06:28 +0000 (UTC) Received: from [10.171.117.215] (public-gprs377903.centertel.pl [37.47.107.112]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) (Authenticated sender: mgorny) by smtp.gentoo.org (Postfix) with ESMTPSA id 731D1340862; Thu, 5 May 2016 11:06:24 +0000 (UTC) User-Agent: K-9 Mail for Android In-Reply-To: <2d15cd19-6f80-60e8-d108-dac83c0bb4d4@gentoo.org> References: <20160502232235.4741324b.mgorny@gentoo.org> <2d15cd19-6f80-60e8-d108-dac83c0bb4d4@gentoo.org> Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Project discussion list X-BeenThere: gentoo-project@lists.gentoo.org Reply-To: gentoo-project@lists.gentoo.org MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset=UTF-8 Subject: Re: [gentoo-project] [RFC] New Overlays project guide From: =?UTF-8?Q?Micha=C5=82_G=C3=B3rny?= Date: Thu, 05 May 2016 12:37:09 +0200 To: gentoo-project@lists.gentoo.org,Daniel Campbell Message-ID: X-Archives-Salt: 9ad129f7-dae6-4aa4-bf5f-ba5144f7e610 X-Archives-Hash: 0bb98fe34e81adf26949dbec765458cd Dnia 5 maja 2016 11:16:19 CEST, Daniel Campbell napisał(a): >On 05/02/2016 02:22 PM, Michał Górny wrote: >> Hello, everyone. >> >> The documentation of Overlays project [1,2,3] is in pretty bad shape >> right now. Aside to being outdated, I find the current form not very >> readable or focused. The large number of short sections makes reading >> harder, and a lot of information is either useless or goes outside >> the scope of project documentation. >> >> For this reason, I would like to replace the documentation with a >new, >> short guide I've written [4]. The goal would be to make it a 'how >> to...' form of guide focused on Gentoo Overlays project-specific >> topics. Right now it covers requesting repositories and reporting >bugs >> on them. Additional topics can be added if necessary. >> >> I would like to explicitly avoid including documentation belonging >> elsewhere such as layman user guides, partial ebuild development >guides >> or VCS guides. >> >> What do you think? >> >> [1]:https://wiki.gentoo.org/wiki/Project:Overlays/Policy >> [2]:https://wiki.gentoo.org/wiki/Project:Overlays/Dev_Guide >> [3]:https://wiki.gentoo.org/wiki/Project:Overlays/User_Guide >> [4]:https://wiki.gentoo.org/wiki/Project:Overlays/New_overlays_guide >> > >This sounds like a great initiative! I think a lot of users sort of >understand the idea of overlays, but don't always realize that they can >start one of their own or help out those that maintain one. Gentoo is >primarily about choice and giving power to the user, so bringing this >to >the forefront is great! > >Small nitpicks I have, however: > >* In [1] under 'Types of overlay', it's mentioned that there are two >types of overlay, and yet four bullets are present. We devs will >probably glean the difference, but an average user may not understand >the difference. Perhaps some "and" or "or"s are in order here. > >* Again in [1], the metastructure document should probably be linked to >in the wiki. I'm a developer and don't know where this is. (of course, >I'm expected to do some searching so it's not a big deal to me >personally, but I'm approaching this with the mindset of a user) > >Otherwise I think your efforts look great so far. Keep it up. :) 1-3 are the docs I'd like to remove. > >[5]: https://github.com/gentoo-mirror/gamerlay/pull/1 -- Best regards, Michał Górny (by phone)