Re: [gentoo-user] NFS mounting - SOLVED

[Peter Humphrey <peter@prh.myzen.co.uk>]

On Tuesday 3 December 2024 13:28:44 Greenwich Mean Time I wrote:
> On Tuesday 3 December 2024 13:08:51 Greenwich Mean Time Matt Jolly wrote:
> > Hi Peter,
> > 
> > On 27 November 2024 2:13:01 am AEST, Peter Humphrey
> > <peter@prh.myzen.co.uk>
> wrote:
> > >Someone needs to have a look at the nfs-utils wiki page. I'd do something
> > >myself, but how? I raised a bug against a document once, only to be
> > >rebuked.
> > 
> > You can raise issues on the "Talk" page for a given article, e.g.
> > https://wiki.gentoo.org/wiki/Talk:Nfs-utils
> > 
> > Ideally, since it's a wiki, if you know how to fix it you can edit the
> > page
> > directly. Don't be afraid, other editors will help polish your
> > contribution
> > if it's a little rough around the edges as long as it's complete.
> > 
> > Trying this from Thunderbird mobile. Hopefully it doesn't mangle the
> > reply!
> 
> That's a real help; thank you Matt.

I've made a suggestion about the nfs-utils page, but I've also been thinking 
about Gentoo wiki documents generally, because I find them unsatisfactory: not 
their content, but the style of presentation. I was documentation manager on a 
200-man-year software project years ago (supplier side), so I think I know 
what I'm talking about [1].

One problem is the apparent absence of structure in the body of the document. 
A table of contents appears at the top, complete with numbered sections and 
subsections in a clear hierarchy, but those numbers appear nowhere else. The 
complexity of most of these documents is such that, once deep into the text, 
the relationship with the rest of it is invisible. This sounds academic, but 
it's real; reliance on font sizes to distinguish headings is not enough on its 
own. An immediate improvement would result from including the numbers from the 
contents list. I imagine it would be comparatively easy to do, as well.

Secondly, the big advantage of viewing on a screen has largely been discarded 
- colour. There are pale coloured backgrounds in some highlights, but I wonder 
whether more could be achieved. I dimly remember the adoption of the present 
style (when was that?), following a 'paper' scheme. (I think that name's 
right.) A consistent style is essential, of course, but why go backwards to an 
earlier technology?

Thirdly, showing terminal commands on a huge black background is much too 
disruptive, visually. They're so overpowering that things like headings 
disappear. I find, especially now my vision is deteriorating, that the 
interleaving of main and secondary topics is often baffling: for instance, the 
choice between openrc and systemd with other alternative streams.

Not enough thought has been given to the combined effect, which is to make the 
documents hard to read and understand.

What does the team think can be done about it?

1.  The fact that the project was cancelled when it became clear that the first 
50% of the work had taken the first 80% of the time, and the second 50% would 
take the other 80% of the time, had nothing to do with the documents.  :_)

-- 
Regards,
Peter.