develooper Front page | perl.perl5.porters | Postings from November 2003

Re: Poor State of the Man Pages

Thread Previous | Thread Next
From:
Abigail
Date:
November 27, 2003 15:58
Subject:
Re: Poor State of the Man Pages
Message ID:
20031127235743.GA22083@abigail.nl
On Thu, Nov 27, 2003 at 10:50:33PM +0200, Shlomi Fish wrote:
> 
> Oh Jesus Christ!
> 
> How many Perl 5 Porters does it take to screw in a lightbulb? Will you
> leave the verb "transliterate" alone? Here are the facts about it:
> 
> 1. It is the proper technical term.
> 
> 2. Its meaning in English is not identical to its technical meaning.
> 
> 3. Plus, not everybody are familiar with the English word, to begin
> with.
> 
> Now, I say that these items warrant a short explanation that explains what
> it means. I don't want to avoid it. We should never avoid the proper
> terms. But we should also explain them.


But when do you stop? If the goal is to write documentation in English
for people who don't master English, when do you stop explaining?
Until you have no multi-syllable words left? Until the documentation is
70% dictionary and 30% technical? Until Dr. Suess approves it?

Don't dumb down the documentation. It'll lose value.


Abigail

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About