Documentation
vitic
not have detailed documentation plus understandable examples of usage.
It is amazing that in many packages the provided usage SYNTAX passes
for documentation.
Many of the packages sit there for years and nobody uses them. What up
with the authors? They spent much of their time creating the package
but are LAZY to provide examples of usage? Their work has been
WAISTED. Including wasted hours of users who try to figure out how the
package works.
Or, somebody, please write a book that documents all the packages
included with the distribution.
---Victor
EL
> Many of the packages sit there for years and nobody uses them. What up
> with the authors? They spent much of their time creating the package
> but are LAZY to provide examples of usage? Their work has been
> WAISTED. Including wasted hours of users who try to figure out how the
> package works.
Can you give examples of such packages?
--
Eckhard
vitic
First of all, I apologize for my tone. Didn't mean to belittle the
hard work of many contributors. I spent my entire weekend trying to
setup a combination of sendmail/cyrus for virtual domains with no luck
and part of that frustration transfered to TCL. I am calming down
now.
One particular package I was talking about is nameserv::server package
to use as a DNS server. As for others, any of them that don't have
"Examples:" section fall in "not very well documented" category, in my
opinion.
Although all of them describe every option/command of their package,
putting it all together is often confusing. Unless a person already
comes with the background knowledge related to that particular
package, it is often difficult to use it without seeing some real life
examples of usage.
---Victor
Gerald W. Lester
> ...
>
> Or, somebody, please write a book that documents all the packages
> included with the distribution.
Thank you for volunteering to write the book!!!
Any idea when ya'll be done?
--
+--------------------------------+---------------------------------------+
| Gerald W. Lester |
|"The man who fights for his ideals is the man who is alive." - Cervantes|
+------------------------------------------------------------------------+
Arnold Snarb
No, no, no! Other way around! We must INCLUDE all of those
extensions IN THE CORE!
The Tcl core is well-documented. If we [*] put all the
badly-documented extensions in the core, then they'll become
well-documented too [**].
[*] and by "we", I mean "somebody else".
[**] the MAGIC DOCUMENTATION FAIRIES will take care of this part.
--AS
Larry W. Virden
> I propose to BAN all extensions included with Tcl distribution
The only extensions that are included with the Tcl distribution are:
http
msgcat
platform
and on Windows, the registry extension and something on MacOS.
If something is missing from the distribution that is preventing you
from using it, then the first step should be, of course, the filing of
a bug report. Now, if on the other hand something is there, but
lacking some information, you might try a bug report, but a feature
request might also be appropriate.
And of course, best of all would be a patch adding the missing
information appropriately.
> that do
> not have detailed documentation plus understandable examples of usage.
> It is amazing that in many packages the provided usage SYNTAX passes
> for documentation.
>
> Many of the packages sit there for years and nobody uses them. What up
> with the authors? They spent much of their time creating the package
> but are LAZY to provide examples of usage? Their work has been
> WAISTED. Including wasted hours of users who try to figure out how the
> package works.
Fascinatingly enough, most authors are not strictly Tcl developers.
Some in fact have families and other jobs which demand some portion of
their time. Then there are those Tcl authors who have burned out
trying to satisfy seemingly never satisfied Tcl users.
This all in general being open source, if someone has a problem with
the current level of support of package, they are free to a) start
providing support on their own, b) hire someone to provide support for
a package, c) contact the original author to try and bribe/blackmail/
entice/motivate them to provide the support needed, or d) find some
other extension or even different programming language that meets the
requirements
>
> Or, somebody, please write a book that documents all the packages
> included with the distribution.
Creating a book documenting dead packages might not be an impossible
task. I doubt the demand for it would justify the hours spend writing
it though. And who is going to pay someone to write said book?
vitic
My apologies to anyone offended.
Your points well taken. Better ask for help before giving up and being
upset.
---Victor
Andrew Mangogna
found one. Thanks for motivating me to add you to my kill list.
Andrew
vitic
> I've been looking for a good reason to filter all your postings and now I
> found one. Thanks for motivating me to add you to my kill list.
>
> Andrew
Talk about overreacting. :) My post wasn't THAT bad. And I did
apologize twice. I was in a bad mood, made a mistake and apologized.
There is nothing else that needs and can be done. No meed to go
overboard on this.
Not that it bothers me that somebody filters me out. That's childish
and uncalled for.
---Victor
Donal K. Fellows
> The Tcl core is well-documented. If we [*] put all the
> badly-documented extensions in the core, then they'll become
> well-documented too [**].
>
> [*] and by "we", I mean "somebody else".
> [**] the MAGIC DOCUMENTATION FAIRIES will take care of this part.
Speaking as one of the people who's done a lot to improve the
documentation in recent years, the amount of magic involved was not so
great as you might suppose.
Donal.
Donal K. Fellows
> I propose to BAN all extensions included with Tcl distribution that do
> not have detailed documentation plus understandable examples of usage.
Which distribution? (Have you considered writing some examples instead?
You can start easily enough just putting them up on the wiki...)
Donal.
Kevin Kenny
An' who-za you callin' a fairy? :)
--
73 de ke9tv/2, Kevin
Kevin Walzer
documentation is exceptionally hard because it takes writing skills,
which are not the same as coding skills.
If anyone is looking for an example of really good documentation, take a
look at Csaba Nemethi's Tablelist documentation at
http://www.nemethi.de/tablelist/index.html. Not only are the commands
thoroughly documented in man-page style, but there's a white paper that
discusses the design of the widget and has lots of sample code and
screenshots.
I've used Csaba's white paper as the style for the documentation I
provide at my own website, e.g.
http://tk-components.sourceforge.net/fileicons/index.html. I've never
learned how to write man pages, so my extensions are lacking in that
department, but I think the detailed prose overview is an acceptable
substitute.
--
Kevin Walzer
Code by Kevin
http://www.codebykevin.com
AndreasK
> One particular package I was talking about is nameserv::server package
> to use as a DNS server.
First, to narrowly address this sentence: "nameserv::server" is not a
DNS server. I has nothing to do with DNS. It is built on top of and
for the 'comm' package.
Looking again at the docs I see that this is not made clear. This will
be fixed.
> As for others, any of them that don't have
> "Examples:" section fall in "not very well documented" category, in my
> opinion.
Not everybody is good at writing examples. I know I am not good at
writing documentation beyond the 'reference' level you are complaining
about. Simply because I am too near to the package, i.e. I know it
well, and that very knowledge makes it difficult for me to see things
from the outside.
That is part of why I added in Tcllib 1.10 a 'Bugs, Feedback' section
to all manpages for packages in Tcllib which provides a --> direct
link to the Tcllib bug tracker. I.e. making it _easy_ to provide
feedback about anything about the package including the documentation
itself.
I would now like to give thanks to Eckhard for drawing the name of one
the packages you are complaining about out of you, for without the
'nameserv::server' catching my attention I would have skipped this
thread as not containing anything I could act on. Meaning that the
documentation of 'nameserv' would have stayed unchanged, with me
unknowing of the problem.
We developers are not mind readers. TIP #131 is a nice joke, it has no
foundation in reality. To know something we have to be told about it,
somewhere where we will actually see it. For Tcllib packages that is
the Tcllib bug tracker.
> Although all of them describe every option/command of their package,
> putting it all together is often confusing. Unless a person already
> comes with the background knowledge related to that particular
> package, it is often difficult to use it without seeing some real life
> examples of usage.
--
Andreas Kupries <akup...@shaw.ca>
Gerald W. Lester
> On Apr 28, 6:37 pm, Andrew Mangogna <amango...@mindspring.com> wrote:
>> I've been looking for a good reason to filter all your postings and now I
>> found one. Thanks for motivating me to add you to my kill list.
>>
>> Andrew
>
>
> Talk about overreacting. :) My post wasn't THAT bad. And I did
> apologize twice. I was in a bad mood, made a mistake and apologized.
Well you could get in your time machine and stop your-previous-self from
posting the message!
Ron Fox
description is in the client side, as that's how one creates names that
can be found. See:
http://aspn.activestate.com/ASPN/docs/ActiveTcl/8.4/tcllib/nns/nns_client.html
as well for the nameserv client documentation.
I guess I find that on the whole with a bit of careful thought, and
reading the Tcl package docs are usually much better than what I see for
typical open source software. Writing good docs is hard and takes
time. Most of the Tcl authors are not paid to write Tcl packages. They
are not lazy, they usually write what they need and want and make it
available in the off chance someone else needs or wants it. They do the
docs in the free time they have.
Ron.
"Walk a mile in my shoes
just walk a mile in my shoes
Before you abuse, criticize and accuse
Then walk a mile in my shoes"
- Joe South.
Andreas Kupries
> Ron.
>
> "Walk a mile in my shoes
> just walk a mile in my shoes
> Before you abuse, criticize and accuse
> Then walk a mile in my shoes"
> - Joe South.
That is a new one to me. I knew only
Before you criticize someone walk a mile in their shoes. That
way, when you criticize them you're a mile away and you have
their shoes.
--
So long,
Andreas Kupries <akup...@shaw.ca>
<http://www.purl.org/NET/akupries/>
Developer @ <http://www.activestate.com/>
-------------------------------------------------------------------------------
vitic
> Even minimal documentation is hard, or at least tedious, to write. Good
> documentation is exceptionally hard because it takes writing skills,
> which are not the same as coding skills.
>
> If anyone is looking for an example of really good documentation, take a
> thoroughly documented in man-page style, but there's a white paper that
> discusses the design of the widget and has lots of sample code and
> screenshots.
>
> I've used Csaba's white paper as the style for the documentation I
> learned how to write man pages, so my extensions are lacking in that
> department, but I think the detailed prose overview is an acceptable
> substitute.
>
> --
> Kevin Walzer
> Code by Kevinhttp://www.codebykevin.com
The most natural and best way of learning (the way we did as little
children) is by following an example. Add one to ten lines of examples
to the man page and it will make all difference in the world.
The only reason I ever learned object oriented programming is because
of the "barking dog" of SNIT and the "soccer club" of XOTcl. Those
examples have taken something very abstract and confusing and made it
easy to grasp. I remembered that a year before I learned it I stumbled
upon XOTcl's command reference. I tried to figure it out and couldn't.
I could not learn it by reading the reference. References are there to
help you with something that you already understand. Needless to say,
I am very grateful to SNIT and XOTcl developers for taking their time
and creating that documentation. My programming style has changed
dramatically and complex projects have become much easier to manage.
---Victor
Donal K. Fellows
> The most natural and best way of learning (the way we did as little
> children) is by following an example. Add one to ten lines of examples
> to the man page and it will make all difference in the world.
I agree, and that's why the Tcl and Tk manual pages now (mostly) have
examples, with the exception of the widgets (where trying out the Tk
widget demo is far better from a pedagogic perspective).
Donal.
vitic
Yes, I have done some of that in the CLT and other places and will
continue to do it.
---Victor
vitic
> Ron Fox <f...@nscl.msu.edu> writes:
> > Ron.
>
> > "Walk a mile in my shoes
> > just walk a mile in my shoes
> > Before you abuse, criticize and accuse
> > Then walk a mile in my shoes"
> > - Joe South.
>
> That is a new one to me. I knew only
>
> Before you criticize someone walk a mile in their shoes. That
> way, when you criticize them you're a mile away and you have
> their shoes.
>
> --
> So long,
> <http://www.purl.org/NET/akupries/>
> Developer @ <http://www.activestate.com/>
> -------------------------------------------------------------------------------
I like that one. :)
---Victor
wi...@wjduquette.com
Woof!
-- Will
vitic
Thanks again Will :)
Take good care of that barking dog ;)
---Victor
vitic
documentation.
1. The official static one created by developers.
2. The wiki type documentation which is a copy of the official one
that also lets users add their comments, examples, workaround, bugs
etc. for each command.
That would lead to a more up to date and detailed documentation that's
created by many people, which will relieve the developers from this
time consuming task.
---Victor
Torsten Berg
> 1. The official static one created by developers.
> 2. The wiki type documentation which is a copy of the official one
> that also lets users add their comments, examples, workaround, bugs
> etc. for each command.
>
> That would lead to a more up to date and detailed documentation that's
> created by many people, which will relieve the developers from this
> time consuming task.
Hmm, I like that idea. It is like the commented documentation of
PostgreSQL at http://www.postgresql.org/docs/8.3/interactive/index.html
where you can add comments.
Torsten
Gerald W. Lester
vitic
That sounds like an idea. I will try to figure out the best way to do
it.
---Victor
Bruce Hartweg
This is already done for most tcl/tk commands.
Goto http://wiki.tcl.tk/<command>
e.g. <http://wiki.tcl.tk/update>
and you usually get a page with a link to the official
man page docs, and then some discussion/examples/pitfalls
of the command. If a page doesn't exist yet, feel free to
create one. If one exists feel free to add more examples
you feel will be helpful.
Bruce
Larry W. Virden
There have been occasions when a command is used in more than one way.
In those cases (think, for instance, a command called "class" !) one
just creates a new **header** for the specific program or extension,
and adds the information specific to that entity there.