Re: Documentation



On 2008-04-28, vitic <vitick@xxxxxxxxx> wrote:

I propose to BAN all extensions included with Tcl distribution 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.

Or, somebody, please write a book that documents all the packages
included with the distribution.

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
.



Relevant Pages

  • Documentation
    ... I propose to BAN all extensions included with Tcl distribution that do ... not have detailed documentation plus understandable examples of usage. ... Many of the packages sit there for years and nobody uses them. ...
    (comp.lang.tcl)
  • Re: Documentation
    ... not have detailed documentation plus understandable examples of usage. ... Many of the packages sit there for years and nobody uses them. ...
    (comp.lang.tcl)
  • Re: Documentation
    ... Thanks for motivating me to add you to my kill list. ... not have detailed documentation plus understandable examples of usage. ... Many of the packages sit there for years and nobody uses them. ...
    (comp.lang.tcl)
  • Re: Request for comments on simple Ada program
    ... What I still do put in the source code - and don't like putting there - is the abstracts for the subprograms and packages. ... But how can I easily cross-link the documentation and the code? ... The conversation seems to be drifting towards Knuth's "literate programming". ...
    (comp.lang.ada)
  • Re: Plain TeX and long tables
    ... >> there's far less tutorial information available for plain users than ... >> authors deign to describe their packages, other than in the odd remark ... the reason why cataloguing of much of ctan is proceeding so slowly. ... documentation. ...
    (comp.text.tex)