Solving the 'strange language' documentation problem

ruby-talk
1

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 :expressionless:

(*) 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/

2

Josef ‘Jupp’ Schugt wrote:

(*) 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. :slight_smile:

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*”)

3

EHLO

Ils sont fous ces Rubyists^H^H^H^H^H^H^HRomains.

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/

4

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

···

----- Original Message -----
From: “Daniel Berger” djberge@qwest.com
To: “ruby-talk ML” ruby-talk@ruby-lang.org
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. :slight_smile:

5

Hello,

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.

…but I promise that you cannot learn this in 24 hours :slight_smile:

Regards,

TAKAHASHI ‘Maki’ Masayoshi E-mail: maki@rubycolor.org

···

“Josef ‘Jupp’ Schugt” jupp@gmx.de wrote:

6

“Hal E. Fulton” hal9000@hypermetrics.com wrote in message news:334f01c2e53c$f8d803e0$0300a8c0@austin.rr.com…

From: “Daniel Berger” djberge@qwest.com
To: “ruby-talk ML” ruby-talk@ruby-lang.org
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. :slight_smile:

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”. :stuck_out_tongue:

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?

:stuck_out_tongue:

Regards,

Dan

···

----- Original Message -----

7

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

Hal

···

----- Original Message -----
From: “TAKAHASHI Masayoshi” maki@rubycolor.org
To: “ruby-talk ML” ruby-talk@ruby-lang.org
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?

8

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.

9

“Daniel Berger” djberg96@hotmail.com wrote in message
news:6e613a32.0303080748.91a41b@posting.google.com…

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

(I - I)

Mikkel

10

From: “TAKAHASHI Masayoshi” maki@rubycolor.org
To: “ruby-talk ML” ruby-talk@ruby-lang.org
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.

···

On Saturday 08 March 2003 10:15 pm, Hal E. Fulton wrote:

----- Original Message -----

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
seth@cql.com

11

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

···

On Sunday 09 March 2003 07:46 am, Mike Campbell wrote:

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.

–
Seth Kurtzberg
M. I. S. Corp.
480-661-1849
seth@cql.com

12

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?

I will assist if you are interested.

Thanks, I’m very interested :slight_smile:

Regards,

TAKAHASHI ‘Maki’ Masayoshi E-mail: maki@rubycolor.org

···

“Hal E. Fulton” hal9000@hypermetrics.com wrote:

13

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?

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.

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

I believe, at least, I’m not dummy :slight_smile:

Regards,

TAKAHASHI ‘Maki’ Masayoshi E-mail: maki@rubycolor.org

···

Seth Kurtzberg seth@cql.com wrote:

14

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.

15

That is quite true. I’ve seen documents written by brilliant people that were
incomprehensible (the documents, not necessarily the people).

···

On Sunday 09 March 2003 11:49 am, Mike Campbell wrote:

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.

–
Seth Kurtzberg
M. I. S. Corp.
480-661-1849
seth@cql.com

16

EHLO

  • On 2003-03-09 23:24

I’ve seen documents written by brilliant people that were
incomprehensible (the documents, not necessarily the people).

One problem with doucments is that there is a culture of “the more
involved the sentences the better the document”.

I own a nice book on writing theses natural sciences/engineering
(unfortunately in German). Becaus a large portion of such theses is
documentation of what one has done I am pretty sure that many of the
hints are useful for other documentations as well. I’ll look into
that.

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

···
17

Hi!

  • On 2003-03-10 00:26 I wrote:

I own a nice book on writing theses natural sciences/engineering
(unfortunately in German). Becaus a large portion of such theses is
documentation of what one has done I am pretty sure that many of
the hints are useful for other documentations as well. I’ll look
into that.

Version 0.1 of ‘Documenting Software’ is available at

http://members.lycos.nl/jupp/documenting/

Any comments are welcome. I will release the text under GFDL as soon
as I am sure how to correctly apply it.

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

18

EHLO

  • On 2003-03-10 23:11
···

I will release the text under GFDL as soon as I am sure how to
correctly apply it.

This has just been done. I also did add a recommendation that other
documentation should be released under GFDL as well.

In my opinion the statement of the license is a very important one
therefore I did change the version number from 0.1 to 0.2.

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