Putting my cheek out there...

I posted on comp.lang.tcl today. I need to make people see that documentation is important. This is what I posted:

...

I posted the initial question because I wanted the experts' point of
view. I am still learning, so I though it would be good to see what
the features are that keep people within the Tcl language.

However, I have to confess that when I saw that list, I saw a list
that sounded a bit "not updated" to me. I mean no disrespect, but as a
newcommmer to the language, I can't help but provide something of a
newbe's view of these points. I hope you'll see them as friendly
comments on something where I think more could be done:

* Rapid development
Certainly true, but up to a point. Finding good, solid information
about how to set up a development cycle for a package with large
number of internal dependencies is not easy (are there any?). For
instance, the "pkg_mkIndex" command seems to assume that all of the
parts of the package is there already. What do I do then when I just
need to check that the part I am working on right now works? I don't
need help on this really (I think I now have a good system for it) but
I need you to see that the process of actually figuring this very
simple and basic step of the development cycle is, to say the least,
opaque. The infrastructure for developing an extension through is much
more transparent.

* Graphical user interfaces
Yes, certainly true. Tk is a feature. Although, it is not only a
feature of Tcl anymore.

* Cross-platform applications
Yes, this is true. Although not unique to Tcl, the cross-platform
nature of the language is a strong feature, and not highlighted
enough. Many languages are "cross platform" but usually not as solidly
so.

* Easy to learn
Yes, well. This is true, up to a point. I think everyone is aware that
the syntax is a bit unorthodox in places, and that scares people. I
know that the rules are simple and consistent, but I have to say that
for a person with mainly C/Java/Python/Perl experience, you get
surprised quite often.

* Mature but Evolving
Yes, mature is a strong point. This should be highlighted more. I
think "stability" also goes into this point.

* Extend, Embed and Integrate
Yes, this is the main feature, and why I stay with Tcl for my current
project. I need cooperation with the R language, and the possibility
of embedding my code into other programs, and Tcl gives me that in an
efficient way.

* Deployment
Hmm, not sure that this is a strong point anymore. I think most
languages have a viable deployment option nowadays. I'm sure that
starkit/starpacks are more evolved than other solutions, but I don't
see a big surge of starpack-based applications. So, maybe this needs
to be proven?

* Testing
Sure, the testing harness and benchmarking command are quite nice.
Needs some documentation though... And, again, testing the accurate
functioning of a command loops back into the problems in setting up
the development environment properly.

* Network-aware applications
Certainly true, but not really unique. The event-based approach is
nice though.

* The Tcl community
Yes, I have gotten good response from this list.

* It's free!
Yes, well.

I would add the excellent handling of UTF-8 and encodings in general.
I see this as a major point - somewhere around 5/6th or something of
the earths population does not speak a language where the ascii
alphabet would be sufficient representation of the writing system, so
this is a strong point (ok, this is a very rough estimate based on the
number of native speakers of languages, so please do not consider this
statement as anything other than wild speculation and a ballpark
figure, so don't quote me on it).
Anyway, the no-fuss handling of UTF-8 should be highlighted more, I
think :-)

What about speed? Is speed a feature? Tcl is not included in, for
instance, the "Computer Language Benchmark Game" (http://
shootout.alioth.debian.org/). Maybe someone would be interested in
submitting code?

What about documentation? Is that a feature? I see some modules with
lots of documentation, and some with none. Maybe there is cause for a
standard API documentation procedure + a standard way of documenting
how to use the code? I suspect that the lack of a purposeful
documentation procedure makes people not put any effort into
documentation. It does not matter what the format is, as long as it is
accessible and produces nice results. Maybe the recent effort to get
Tcl capability into doxygen is the way to go (I've used Natural Docs
myself, successfully), as long as it affords the package developer to
write documentation on the usage of the _use_ of the code, not just
what each procedure does. I think it could be a feature, if the
community put focus into one effort.

What about interoperability with code developed in other languages? Is
this a feature? I see code for calling (or be called from) C (of
course), Java, Python and R (at least call). Are there others?

I think what I want to say here is that the list I found on the tcl.tk
did not sound current. There are issues, I think, with some of the
points put forward there, and there are other that I would stress
instead.
...

Hope noone is offended by this...