[gentoo-project] [RFC] New Overlays project guide

[gentoo-project] [RFC] New Overlays project guide

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 1176 bytes --]

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

-- 
Best regards,
Michał Górny
<http://dev.gentoo.org/~mgorny/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 949 bytes --]

Re: [gentoo-project] [RFC] New Overlays project guide

[Anthony G. Basile]

On 5/2/16 5: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
> 


I like it.

-- 
Anthony G. Basile, Ph.D.
Gentoo Linux Developer [Hardened]
E-Mail    : blueness@gentoo.org
GnuPG FP  : 1FED FAD9 D82C 52A5 3BAB  DC79 9384 FA6E F52D 4BBA
GnuPG ID  : F52D4BBA

Re: [gentoo-project] [RFC] New Overlays project guide

[Daniel Campbell]

[-- Attachment #1.1: Type: text/plain, Size: 2377 bytes --]

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. :)

[5]: https://github.com/gentoo-mirror/gamerlay/pull/1

-- 
Daniel Campbell - Gentoo Developer
OpenPGP Key: 0x1EA055D6 @ hkp://keys.gnupg.net
fpr: AE03 9064 AE00 053C 270C  1DE4 6F7A 9091 1EA0 55D6


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [gentoo-project] [RFC] New Overlays project guide

[Michał Górny]

Dnia 5 maja 2016 11:16:19 CEST, Daniel Campbell <zlg@gentoo.org> 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)