Re: debian-faq (was ... Re: upgrade to Wheezy fails with aptitude)
On 04/04/12 19:01, Andrei POPESCU wrote:
> On Mi, 04 apr 12, 11:38:29, Scott Ferguson wrote:
>> My suggestions:-
>>
>> 1. rephrased for clarity, but hardly succin*c*t.
>> Note that since Lenny, apt-get installs recommended[*1] packages by default.
>> Beginning with the release of Squeeze[*2], apt is the recommended
>> program to perform system installation and major system upgrades.
>>
>> 2. How I'd write it:-
>> Apt is the recommended program to perform system installation and major
>> system upgrades.[*3]
>>
>> 3. To avoid confusion people should read the fine Debian documentation
>> in their native language.
>
> Not fair, most languages don't have enough contributors to translate the
> documentation, and translations may have issues themselves.
That's a problem that requires solving, the alternative is to expect
people to master a second language. That *is not fair*.
>
>> [*1] tempting to treat that as a noun :-)
>
> I see where you're coming from, but wouldn't it be too much jargon?
IMO Yes (too much jargon).
Best to keep it simple. Footnotes could be used for those who don't
understand what "recommended" means in the context of Debian packaging
Is the question "which tool to upgrade?" or "which tool is best to
install packages?" They both have correct answers, but only the second
question has multiple correct answers.
My preference is "drill up" for detail in this instance (the basics are
most easily accessed). It's like instructions for operating a vending
machine as opposed to a manual for building one. Developer docs and mans
should be drill down for simple.
>
>> [*2] Surely outdated advice for archived releases belongs in the
>> archives. IMO counter arguments don't belong in documentation, they
>> usually only appear there as a futile attempt to quiet the trolls.
>
> Do you mean the mention of aptitude? I don't see it as a counter
> argument, but a genuine recommendation. As mentioned elsewhere in this
> thread, it's very useful for me and probably others too.
No. I meant the historical context (before, since, etc).
Aptitude works well for many people - as do other package managers. Are
any but apt relevant in this particular context?
If I were writing instructions for a plant label on how to pot the plant
out - I'll recommend using a spade for digging a hole. Other implements
can be used to dig holes, and in some situations are better than (some)
spades, and then there are different spades.... but that information
belongs in a booklet/degree "How to dig a hole".
(Yes, you can use a shovel, but a spade is recommended)
>
> One more try:
>
> Note that since Lenny, apt-get installs recommended packages by
> default.
I suspect that would be correctly understood by most English speakers.
I would insert a footnote explaining "recommended" and possibly the
relevant stanza in apt.conf.
> Beginning with the release of Squeeze,
Some will have problems with the historical context - does that mean
that on that day all Debian releases "installed recommended"?
And is it relevant? (it's not Debian FAQ 2008).
> apt-get is also the
> recommended program to perform system installation and major system
> upgrades.
Some will want to know why waijig and cupt aren't mentioned.
Perhaps the following belongs in a footnote also.
> aptitude may be preferred for interactive use.
<snipped>
IMO the documentation should be written (and read) in the current
context, which is Squeeze and later. Historical references only confuse
the issue. I maintain a number of older Debian installs (Sarge and Etch)
- but I don't expect the current documentation to be relevant to them,
or Spud. Then there's the future...
>
> Kind regards,
> Andrei
Kind regards
--
Iceweasel/Firefox/Chrome/Chromium/Iceape/IE extensions for finding
answers to questions about Debian:-
https://addons.mozilla.org/en-US/firefox/collections/Scott_Ferguson/debian/
Reply to: