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