Re: Release notes
Daniel Hartwig wrote:
Justin B Rye <justin.byam.rye@gmail.com> wrote:
>> Daniel Hartwig wrote:
>>>
>>> Right, and I do not see how ‘visual mode’ is misleading?
>>
>> I've explained it already, but the reason it's not obvious to you is
>> that you're not some
>>
>> slow-witted, ignorant newbie,
>>
>> and therefore don't have much practice looking at documentation
>> from the appropriate angle.
>
> Ok, I was not aware that the release notes were attempting to cater to
> such a special interest group.
It's the first law of documentation: don't write it for people who are
brilliant, knowlegeable experts on the subject. You don't need to
assume they're drooling morons, but you at least need to write for an
imagined audience of outsiders - people who who *don't* already know
the things you're telling them.
It's plausible that man pages really are intended for readers who are
familiar with the Unix command line as a way of life with its own
traditional jargon; but that just means precedents set by man pages
shouldn't be binding on other forms of documentation.
>> You're using the term "visual mode" to distinguish that UI
>> from another one, which is therefore... what, "olfactory mode"? Are
>> users not expected to read "Accept this solution? [Y/n/q/?]" using
>> their eyes?
>
> That would be the command line interface, which is more verbal than
> visual in nature.
It's still 100% visual. Indeed, I would argue that the CLI is *more*
dependent on vision, in that it always requires a short-sighted user
to squint at the individual words - you can't just try a removal,
recognise a screen full of magenta and red as a warning sign, and back
out; you have to reach for your reading glasses.
"Visual mode" would be a good self-explanatory name for it if the
alternative was "Braille mode". But how is an outsider supposed to
guess that "visual mode" means "package-browser mode"?
>>> By the way,
>>> current aptitude manual prefers the term ‘visual interface’, ‘mode’ is
>>> used only once and I have just changed that.
>>
>> So even if our policy is "stick to the canonical label", we ought to
>> change it.
>
> No, this was just a note. The two terms are similar enough with the
> key word being visual. Both documents have used their respective
> terms for some time, so no pressing reason to change.
This appears to be one of those cases where bad ideas become required
standards just by virtue of being *old* mistakes, with no further
justification required.
>> Alternatively, if you still think "visual" is a valid
>> description as well as just an arbitrary label,
>
> I do not think it is an arbitrary label.
>
>> why shouldn't we use
>> other valid descriptions as well?
>
> Consistency with the aptitude manual.
Seriously? We're never allowed to describe anything in terms that
aren't used in the technical manual? Entry-level documentation that
starts out by phrasing things in less obscure terms is *forbidden*,
even if it goes on to introduce the official jargon later?
Remember, the mentions of aptitude in the release notes are alongside
mentions of software like debfoster and cruft; readers may or may not
even have been particularly aware that these packages existed before,
let alone being so used to the specialised jargon in their manuals
that we'd confuse them by avoiding it.
> If you do not care for that,
> then do what you like. I don't see any reason to change it in
> aptitude, but then I am not in the habit of catering to the
> aforementioned special interest group.
This is one of those classic indicators that maybe writing
documentation isn't a task you're really cut out for. But feel free
at any moment to stop actively sabotaging the efforts of people who
are doing their best to improve things.
I should probably tone that down a bit, but excuse me, there's a new
DPN to proofread and I'm hoping that'll be more relaxing and
productive.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: