The wiki [was: Re: Soft scrolling on framebuffer consoles]

Alan Mackenzie <[email protected]> writes:

>>   https://wiki.gentoo.org/wiki//etc/portage/patches
>
> That is not a well written page.  There is no coherent 
> description of
> how one specifies the version(s) of a package a patch should be 
> applied
> to.  Just some cryptic meta-specifications and a few vague 
> examples.

Fair. The wiki is a volunteer effort, only a small number of us 
are regularly working on it (with much of that work focused on 
improving the Handbook), and many of those who contribute / have 
contributed to the wiki aren't native/fluent English speakers. i 
try to encourage people to help out, but as i say: "Many people 
want good documentation; far fewer are willing to help make that 
happen."

> The text ought to say what ranges of versions can be specified, 
> and how
> to do so.

Indeed.

Something that typically comes up in discussions about 
contributing to the wiki is: "Oh I can't contribute unless I'm 
familiar with the subject matter of a given page." Overall, this 
isn't the case; there's always work needing to be done that 
doesn't require _any_ familiarity with _any_ of the subject 
matter, e.g. fixing typos and template usage. But more 
specifically, i myself am _often_ not familiar with the subject of 
a page that clearly needs work, and this page is a good example.

In this sort of situation, what i end up doing is:

* searching for, and within, any related documentation i can find;
* manually testing scenarios and behaviours (which sometimes 
  reveals inconsistencies with the docs); and
* occasionally spelunking through source code (including in 
  languages i only have a vague knowledge of) in order to 
  understand or clarify certain behaviours.

i appreciate that many - most? - people don't have the time or 
inclination to do this. But i'll also say that, for those who are 
using Gentoo as a method of getting a deeper knowledge of how 
Linux systems can work, improving a wiki page by going through the 
above process might be a useful learning exercise, in addition to 
being a contribution to the Gentoo community. 


Alexis.
https://wiki.gentoo.org/wiki/User:Flexibeast