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.
--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)