Re: FAQ wording (was: Re: Desolate Condition)

[Jason Liu]

>
> What if the end of the first sentence was changed to: "ports will be
> installed for only the architecture you're currently running on."?
>

Besides being the most concisely worded, I also find this version to be the
most unambiguous. I think leaving the words "build/built" and "compile" out
of the sentence entirely would be for the best.

-- 
Jason Liu


On Mon, Apr 5, 2021 at 10:15 AM wowfunha...@gmail.com 
wrote:

> > It's a tricky thing to state both concisely and accurately because the
> > compilation may indeed happen on the user's computer after installation
> > is requested. Or it may not. The ambiguity of whether "be compiled" is a
> > verb in the passive voice ("the code is being compiled") or a
> > description of a state ("this is code compiled for x86_64") may reflect
> > the author's awareness of the undecidedness of which one will actually
> > happen.
> >
> > Improvements to the text's clarity are very welcome, of course.
> >
> > - Josh
>
> What if the end of the first sentence was changed to: "ports will be
> installed for only the architecture you're currently running on."?
> Basically mirroring the other change made on Saturday.
>
>
>

Re: FAQ wording (was: Re: Desolate Condition)

[wowfunha...@gmail.com]

> It's a tricky thing to state both concisely and accurately because the 
> compilation may indeed happen on the user's computer after installation 
> is requested. Or it may not. The ambiguity of whether "be compiled" is a 
> verb in the passive voice ("the code is being compiled") or a 
> description of a state ("this is code compiled for x86_64") may reflect 
> the author's awareness of the undecidedness of which one will actually 
> happen.
> 
> Improvements to the text's clarity are very welcome, of course.
> 
> - Josh

What if the end of the first sentence was changed to: "ports will be installed 
for only the architecture you're currently running on."? Basically mirroring 
the other change made on Saturday.

FAQ wording (was: Re: Desolate Condition)

[Joshua Root]

On 2021-4-4 11:20 , Kevin Reid wrote:
On Sat, Apr 3, 2021 at 5:22 PM wowfunha...@gmail.com 
 > wrote:


I know it's just one data point, but I thought the replies I got on
this Hacker News comment today were interesting. I can understand
why he/she got confused, and I wonder if there's anything MacPorts
could do to make it clearer.
https://news.ycombinator.com/item?id=26678498



As worded, the FAQ text "the ports you install will be compiled only for 
the architecture you're currently running on" implies (in the linguistic 
rather than logical sense) that the compilation happens after you 
request installation. The minimal patch would be to change the tense to 
"will *have been* compiled only for", but an even better rewording might 
be something like


"…the ports' installed binaries will have been compiled for your
computer's architecture…"


to avoid putting the user's computer in any active role in that sentence 
and to make it clear we're talking about the binaries and not the 
compilation process per se. Perhaps "will contain machine code for" 
would be even more rigorous, but it might be less familiar.


Of course, this sentence may not be the whole problem, but it's what I 
saw in that thread, it's likely /part/ of the problem, and it made a 
good example of the kind of sentence that can be read differently by a 
reader not already familiar with the subjet.


It's a tricky thing to state both concisely and accurately because the 
compilation may indeed happen on the user's computer after installation 
is requested. Or it may not. The ambiguity of whether "be compiled" is a 
verb in the passive voice ("the code is being compiled") or a 
description of a state ("this is code compiled for x86_64") may reflect 
the author's awareness of the undecidedness of which one will actually 
happen.


Improvements to the text's clarity are very welcome, of course.

- Josh