Solving the 'strange language' documentation problem 
Author Message
 Solving the 'strange language' documentation problem

Dear Rubyists,

let's try to escape the 'use language foobarbaz' feedback loop and
let me suggest an idea how we (as a community) may be able to cope
with the 'strange language' problem. With 'strange language' I mean a
language that is only spoken by few people that are no native
speakers.

I am pretty sure that almost any Rubyist is capable of writing a
documentation in at least one language that uses a latin-based
alphabet and that is of Germanic or a Roman origin. That can be but
is not restricted to:

English
Esperanto
French
German and similar languages like Dutch, Afrikaans, etc. (+)
Italian
Latin (*)
Portugese
Romanian
Spanish

What makes them prefer their own language is that they fear to make
so may mistakes that nobody can read their documentation. This is the
problem I want to target.

In order to encourage the use of more widely understood languages we
should not require the use of a specific language but rather work on
realizing the following three-stage process:

Step 1: The author of a software provides a documentation in at least
        one of the languages listed above (or any other non-strange
        language).

Step 2: Someone strongly interested in the software translates that
        documentation into English (because that language is
        understood by the largest number of people worldwide).

Step 3: People that want to make use of the software proofread the
        translation of the documentation.

If the documentation is written in English we can skip Step 2.
Step 3 is crucial because it allows for (maybe lots of) mistakes in
the preceeding steps.

I am sure that if this process is a quite natural one. Indeed it is
what quite often happens without any external influence. If there is
a problem it almost always occurs in Step 1: If a documentation is
written in a slavic language, Chinese, Japanese or Korean there may
be many people interested in using the software but there are only
very few people that are *capable* of doing a translation and feel a
need for a translation.

If someone has software I find interesting and thinks he better
writes documentation in German, Dutch or the like I am willing to do
a translation.

Two remarks on languages:

(+) Dutch: I never did learn Dutch but (possibly because I am German
and did learn English as first and French as second foreign language)
I am able to understand technical texts and even the news written in
Dutch. Nevertheless I cannot understand spoken Dutch :-|

(*) Latin: It is indeed no problem to write technical documentation
in Latin. The Holy See does use Latin as its official language and
did invest *much* energy into a modern Latin dictionary that allows
them to write documents about today's issues in Latin.

Josef 'Jupp' Schugt <jupp (at) gmx.de>             http://www.*-*-*.com/



Wed, 24 Aug 2005 05:41:23 GMT  
 Solving the 'strange language' documentation problem

Quote:

> (*) Latin: It is indeed no problem to write technical documentation
> in Latin. The Holy See does use Latin as its official language and
> did invest *much* energy into a modern Latin dictionary that allows
> them to write documents about today's issues in Latin.

> Josef 'Jupp' Schugt <jupp (at) gmx.de>           http://jupp.tux.nu/

I knew I could put my M.A. in Classics to use in the computer field
someday!

BWAHAHAHAHAHA!

Of course, I'll have to look up some of the modern words. :)

Dan

--
a = [74, 117, 115, 116, 32, 65, 110, 111, 116, 104, 101, 114, 32, 82]
a.push(117,98, 121, 32, 72, 97, 99, 107, 101, 114)
puts a.pack("C*")



Wed, 24 Aug 2005 06:03:47 GMT  
 Solving the 'strange language' documentation problem
What about using the Little Orphan Annie Secret Decoder Ring??

Quote:
-----Original Message-----

Sent: Friday, March 07, 2003 4:04 PM

Subject: Re: Solving the 'strange language' documentation problem


> (*) Latin: It is indeed no problem to write technical documentation
> in Latin. The Holy See does use Latin as its official language and
> did invest *much* energy into a modern Latin dictionary that allows
> them to write documents about today's issues in Latin.

> Josef 'Jupp' Schugt <jupp (at) gmx.de>           http://jupp.tux.nu/

I knew I could put my M.A. in Classics to use in the computer field
someday!

BWAHAHAHAHAHA!

Of course, I'll have to look up some of the modern words. :)

Dan

--
a = [74, 117, 115, 116, 32, 65, 110, 111, 116, 104, 101, 114, 32, 82]
a.push(117,98, 121, 32, 72, 97, 99, 107, 101, 114)
puts a.pack("C*")



Wed, 24 Aug 2005 06:13:49 GMT  
 Solving the 'strange language' documentation problem

Quote:
----- Original Message -----


Sent: Friday, March 07, 2003 4:03 PM
Subject: Re: Solving the 'strange language' documentation problem

> > (*) Latin: It is indeed no problem to write technical documentation
> > in Latin. The Holy See does use Latin as its official language and
> > did invest *much* energy into a modern Latin dictionary that allows
> > them to write documents about today's issues in Latin.

> > Josef 'Jupp' Schugt <jupp (at) gmx.de>           http://jupp.tux.nu/

> I knew I could put my M.A. in Classics to use in the computer field
> someday!

> BWAHAHAHAHAHA!

> Of course, I'll have to look up some of the modern words. :)

Indeed... once I bought a Latin/English dictionary mostly
as a matter of curiosity. I was amused and gratified to
browse it and learn that the Latin word for "spaceship"
was "astronavis."

Cheers,
Hal



Wed, 24 Aug 2005 14:32:45 GMT  
 Solving the 'strange language' documentation problem

Quote:
> ----- Original Message -----


> Sent: Friday, March 07, 2003 4:03 PM
> Subject: Re: Solving the 'strange language' documentation problem

> > > (*) Latin: It is indeed no problem to write technical documentation
> > > in Latin. The Holy See does use Latin as its official language and
> > > did invest *much* energy into a modern Latin dictionary that allows
> > > them to write documents about today's issues in Latin.

> > > Josef 'Jupp' Schugt <jupp (at) gmx.de>           http://jupp.tux.nu/

> > I knew I could put my M.A. in Classics to use in the computer field
> > someday!

> > BWAHAHAHAHAHA!

> > Of course, I'll have to look up some of the modern words. :)

> Indeed... once I bought a Latin/English dictionary mostly
> as a matter of curiosity. I was amused and gratified to
> browse it and learn that the Latin word for "spaceship"
> was "astronavis."

> Cheers,
> Hal

Whew - I'm glad you cleared that up.  I almost gave up when I couldn't
translate "spaceship operator".  Now I know that it's "astronavis
effector". :-P

I did manage to find this link:

http://www.obta.uw.edu.pl/~draco/docs/voccomp.html

I'm sure there must be more complete ones out there.  I suppose I
could order the Oxford Latin Dictionary.  A bargain at at mere $295.

Hmm...does this mean I should use all caps and no punctuation?  And
wtf should I do about representing zero?

:-P

Regards,

Dan



Wed, 24 Aug 2005 23:48:15 GMT  
 Solving the 'strange language' documentation problem


Quote:
> Hmm...does this mean I should use all caps and no punctuation?  And
> wtf should I do about representing zero?

(I - I)

Mikkel



Thu, 25 Aug 2005 00:47:48 GMT  
 Solving the 'strange language' documentation problem
EHLO

<Asterix>Ils sont fous ces Rubyists^H^H^H^H^H^H^HRomains.</Asterix>

Nobody to comment on the suggested process? Or did I miss the
announcement of 'Teach yourself Japanese in 24 hours' or 'Japanese
for Dummies'?

<^_^>

Josef 'Jupp' Schugt <jupp (at) gmx.de>            http://jupp.tux.nu/



Thu, 25 Aug 2005 07:36:01 GMT  
 Solving the 'strange language' documentation problem
Hello,


Quote:
> Nobody to comment on the suggested process? Or did I miss the
> announcement of 'Teach yourself Japanese in 24 hours' or 'Japanese
> for Dummies'?

IMHO, what we need is 'Writing documents in English
for dummies' or 'Teach yourself Reference Manual in 21 days'
or 'Writing English Document: The Pragmatic Programmer's Guide'.
And then let Japanese developers read them.

There are a lot of textbooks and guides of writing, but they
are too general purpose. I want to read more specific one,
focused on documents for library of programing language.

 * template of documents
 * list of keywords frequently used in documents like
   README, reference manual and tutorial
 * list of common expressions (and thesaurus?)
 * ...and so on

It's not problem whether it is written in English or Japanese.
If it's written English, It's useful for not only Japanese,
but other language speakers.

Does anyone know such documents?

P.S.
http://www.geocities.com/takasugishinji/japanese/
..but I promise that you cannot learn this in 24 hours :-)

Regards,




Thu, 25 Aug 2005 08:49:53 GMT  
 Solving the 'strange language' documentation problem

Quote:
----- Original Message -----


Sent: Saturday, March 08, 2003 6:49 PM
Subject: Re: Solving the 'strange language' documentation problem

> IMHO, what we need is 'Writing documents in English
> for dummies' or 'Teach yourself Reference Manual in 21 days'
> or 'Writing English Document: The Pragmatic Programmer's Guide'.
> And then let Japanese developers read them.

> There are a lot of textbooks and guides of writing, but they
> are too general purpose. I want to read more specific one,
> focused on documents for library of programing language.

>  * template of documents
>  * list of keywords frequently used in documents like
>    README, reference manual and tutorial
>  * list of common expressions (and thesaurus?)
>  * ...and so on

> It's not problem whether it is written in English or Japanese.
> If it's written English, It's useful for not only Japanese,
> but other language speakers.

> Does anyone know such documents?

If one does not exist, maybe we can make one.
I will assist if you are interested.

Hal



Thu, 25 Aug 2005 13:15:07 GMT  
 Solving the 'strange language' documentation problem

Quote:
> ----- Original Message -----


> Sent: Saturday, March 08, 2003 6:49 PM
> Subject: Re: Solving the 'strange language' documentation problem

> > IMHO, what we need is 'Writing documents in English
> > for dummies' or 'Teach yourself Reference Manual in 21 days'
> > or 'Writing English Document: The Pragmatic Programmer's Guide'.
> > And then let Japanese developers read them.

I can help with this also.  However, no "dummies."  I've always wondered
exactly why anyone would read a "dummies" book.  In any event, I doubt very
much anyone on the ruby list qualifies as a dummy.

Quote:

> > There are a lot of textbooks and guides of writing, but they
> > are too general purpose. I want to read more specific one,
> > focused on documents for library of programing language.

> >  * template of documents
> >  * list of keywords frequently used in documents like
> >    README, reference manual and tutorial
> >  * list of common expressions (and thesaurus?)
> >  * ...and so on

> > It's not problem whether it is written in English or Japanese.
> > If it's written English, It's useful for not only Japanese,
> > but other language speakers.

> > Does anyone know such documents?

> If one does not exist, maybe we can make one.
> I will assist if you are interested.

> Hal

--
Seth Kurtzberg
M. I. S. Corp.
480-661-1849



Thu, 25 Aug 2005 13:20:32 GMT  
 Solving the 'strange language' documentation problem

Quote:
> IMHO, what we need is 'Writing documents in English
> for dummies' or 'Teach yourself Reference Manual in 21 days'
> or 'Writing English Document: The Pragmatic Programmer's Guide'.
> And then let Japanese developers read them.

I'd think a few of the native English speakers would do well by reading them
also.


Thu, 25 Aug 2005 22:46:06 GMT  
 Solving the 'strange language' documentation problem

Quote:
> > IMHO, what we need is 'Writing documents in English
> > for dummies' or 'Teach yourself Reference Manual in 21 days'
> > or 'Writing English Document: The Pragmatic Programmer's Guide'.
> > And then let Japanese developers read them.

> I'd think a few of the native English speakers would do well by reading
> them also.

Hey, like, you mean, ugh, we don't, like, talk too, uh, good?

--
Seth Kurtzberg
M. I. S. Corp.
480-661-1849



Fri, 26 Aug 2005 00:02:42 GMT  
 Solving the 'strange language' documentation problem

Quote:
> > There are a lot of textbooks and guides of writing, but they
> > are too general purpose. I want to read more specific one,
> > focused on documents for library of programing language.

> >  * template of documents
> >  * list of keywords frequently used in documents like
> >    README, reference manual and tutorial
> >  * list of common expressions (and thesaurus?)
> >  * ...and so on

> > It's not problem whether it is written in English or Japanese.
> > If it's written English, It's useful for not only Japanese,
> > but other language speakers.

> > Does anyone know such documents?

> If one does not exist, maybe we can make one.

We should start at RubyGarden/ruby-doc Wiki or ruby-doc ML?

Quote:
> I will assist if you are interested.

Thanks, I'm _very_ interested :-)

Regards,




Fri, 26 Aug 2005 02:08:19 GMT  
 Solving the 'strange language' documentation problem

Quote:

> > > IMHO, what we need is 'Writing documents in English
> > > for dummies' or 'Teach yourself Reference Manual in 21 days'
> > > or 'Writing English Document: The Pragmatic Programmer's Guide'.
> > > And then let Japanese developers read them.

> I can help with this also.  However, no "dummies."

I think that "... for dummies" means "for people who
don't have any previous knowledge/backgrounds and don't
have enough time/motivation to learn them fundamentally."
correct?

Quote:
>  I've always wondered
> exactly why anyone would read a "dummies" book.

If something gives enough knowlegde for dummies, it also
gives that for average people and beyond-the-average people
(even if it's verbose and redundant for them).

I know there are many "dummies" books that give uncorrect,
invalid and mis-leading informations. But some "dummies"
books are well-targeting, easy-to-read and
omitting complex details. I want the latter "dummies"
guides.

Quote:
>  In any event, I doubt very
> much anyone on the ruby list qualifies as a dummy.

I believe, at least, I'm not dummy :-)

Regards,




Fri, 26 Aug 2005 02:10:06 GMT  
 Solving the 'strange language' documentation problem

Quote:
> > IMHO, what we need is 'Writing documents in English
> > > for dummies' or 'Teach yourself Reference Manual in 21 days'
> > > or 'Writing English Document: The Pragmatic Programmer's Guide'.
> > > And then let Japanese developers read them.

> > I'd think a few of the native English speakers would do well by reading
> > them also.

> Hey, like, you mean, ugh, we don't, like, talk too, uh, good?

Even those who talk well can write like crap, and I'm not excluding myself from
that group.


Fri, 26 Aug 2005 02:49:56 GMT  
 
 [ 19 post ]  Go to page: [1] [2]

 Relevant Pages 

1. Reminder: CADE-15 WS 'Problem Solving...'

2. CADE 15 Workshop 'Problem-solving Methodologies...'

3. stream('file','c','seek ='x) problem

4. C5.5 vs Tintools - Can't solve problem

5. Problem (probably simple) that I can't solve

6. RubyStudio's problem with -r solved

7. problem solved, but I don't know why (was: GNAT implementation bug)

8. CFP: OLCP'01 On-Line combinatorial problem solving and Constraint Programming

9. Script 'nesting' -- SOLVED

10. A small problem that i can'y solve

11. 'space commands' to solve major/minor

12. Conditional Expressions don't solve the problem

 

 
Powered by phpBB® Forum Software