| 1 |
On 05/02/2016 02:22 PM, Michał Górny wrote: |
| 2 |
> Hello, everyone. |
| 3 |
> |
| 4 |
> The documentation of Overlays project [1,2,3] is in pretty bad shape |
| 5 |
> right now. Aside to being outdated, I find the current form not very |
| 6 |
> readable or focused. The large number of short sections makes reading |
| 7 |
> harder, and a lot of information is either useless or goes outside |
| 8 |
> the scope of project documentation. |
| 9 |
> |
| 10 |
> For this reason, I would like to replace the documentation with a new, |
| 11 |
> short guide I've written [4]. The goal would be to make it a 'how |
| 12 |
> to...' form of guide focused on Gentoo Overlays project-specific |
| 13 |
> topics. Right now it covers requesting repositories and reporting bugs |
| 14 |
> on them. Additional topics can be added if necessary. |
| 15 |
> |
| 16 |
> I would like to explicitly avoid including documentation belonging |
| 17 |
> elsewhere such as layman user guides, partial ebuild development guides |
| 18 |
> or VCS guides. |
| 19 |
> |
| 20 |
> What do you think? |
| 21 |
> |
| 22 |
> [1]:https://wiki.gentoo.org/wiki/Project:Overlays/Policy |
| 23 |
> [2]:https://wiki.gentoo.org/wiki/Project:Overlays/Dev_Guide |
| 24 |
> [3]:https://wiki.gentoo.org/wiki/Project:Overlays/User_Guide |
| 25 |
> [4]:https://wiki.gentoo.org/wiki/Project:Overlays/New_overlays_guide |
| 26 |
> |
| 27 |
|
| 28 |
This sounds like a great initiative! I think a lot of users sort of |
| 29 |
understand the idea of overlays, but don't always realize that they can |
| 30 |
start one of their own or help out those that maintain one. Gentoo is |
| 31 |
primarily about choice and giving power to the user, so bringing this to |
| 32 |
the forefront is great! |
| 33 |
|
| 34 |
Small nitpicks I have, however: |
| 35 |
|
| 36 |
* In [1] under 'Types of overlay', it's mentioned that there are two |
| 37 |
types of overlay, and yet four bullets are present. We devs will |
| 38 |
probably glean the difference, but an average user may not understand |
| 39 |
the difference. Perhaps some "and" or "or"s are in order here. |
| 40 |
|
| 41 |
* Again in [1], the metastructure document should probably be linked to |
| 42 |
in the wiki. I'm a developer and don't know where this is. (of course, |
| 43 |
I'm expected to do some searching so it's not a big deal to me |
| 44 |
personally, but I'm approaching this with the mindset of a user) |
| 45 |
|
| 46 |
Otherwise I think your efforts look great so far. Keep it up. :) |
| 47 |
|
| 48 |
[5]: https://github.com/gentoo-mirror/gamerlay/pull/1 |
| 49 |
|
| 50 |
-- |
| 51 |
Daniel Campbell - Gentoo Developer |
| 52 |
OpenPGP Key: 0x1EA055D6 @ hkp://keys.gnupg.net |
| 53 |
fpr: AE03 9064 AE00 053C 270C 1DE4 6F7A 9091 1EA0 55D6 |
Archives