Re: printing errors in octave/matlab

[Paul Kienzle]

On Mar 16, 2004, at 12:58 PM, Bart Vandewoestyne wrote:

> So... any suggestions on the document format?  HTML?  LaTeX?  Wiki?
> Other formats that are more appropriate for converting to many other
> formats?

It's not so much document format that matters as it is the ability for
the medium to ease communication.

Wiki's are good for collecting information from a bunch of people
and allowing others to add to it later.  With aggressive editors
who don't mind doing a little revising of others contributions, a
wiki page can answer a question succinctly.

Mailing lists do not do so well, since the editing chore falls on the
reader.  In their responses and corrections, the authors tend
not to give a complete response to the question, and it is up to
the reader to read all the responses an form the summary themselves.

Web fora (e.g., http://www.macosxhints.com) are a little better than 
mailing
lists since at least the threading structure is imposed, but without the
ability to modify what other people say, the editing work still lies 
with the
reader.

Stand-alone documents are fine given an enthusiastic author.
In many cases, though, enthusiasm quickly wanes and the document
isn't maintained, or the more usual case, isn't posted in the first 
place :D
Take my compatibility FAQ as an example.  It is still pegged to about
version 2.1.36 or so.  If someone reading the document finds that it
is no longer true, they could go to the trouble of contacting me and
trying to correct it.   They don't (because nobody reads it?), which is
fortunate because that means less work for me.  But if the FAQ were
wikified, then readers could enter corrections by hitting the Edit 
button
on the bottom of the page and I don't have to be involved.

Wikis do have a big problem in that they are 'pull' documents.  I'm
not very good at checking them, especially the inactive ones like
http://wiki.octave.org.  For example, I did not know that Michael Creel
posted a "request for comments" on the interface to the optimization
package even though I suggested that he do so.

Unless the wiki maintainers get aggressive and figure out some
way to turn it into a 'push' medium, I don't think it will work for our
community.

For example, a mail gateway so that people can 'watch'  a
particular page or the whole wiki, and ideally modify the wiki by
responding to the posts would take the burden of remembering
to check off me.  Hmmm... I wonder if I can do this client-side with
a Tcl script cron job...

Also, syntax highlighting showing all changes in the last xxx days
or since the last change would make it easy to read the changes
in context. wikidiff (http://pascal.scheffers.net/wikidiff) for the the
Tclers wiki (http://mini.net/tcl) is a convenient digest form, since
it gives word-level highlighted differences rather than you having
to check the page yourself.  Many of the changes are spelling
corrections and minor rewording, so this service is particularly
beneficial.

The other problem with a wiki is that it doesn't readily translate
to a printable form.  Or maybe that's a feature ;-)

Paul Kienzle
address@hidden



-------------------------------------------------------------
Octave is freely available under the terms of the GNU GPL.

Octave's home on the web:  http://www.octave.org
How to fund new projects:  http://www.octave.org/funding.html
Subscription information:  http://www.octave.org/archive.html
-------------------------------------------------------------