[Axiom-developer] RE: Ping: case insensitive filesystems

[Page, Bill]

On Wednesday, November 15, 2006 9:47 AM Gaby wrote:
> ... 
> Not because you can come up with a silly explanation means that
> any explanation should be silly.  Please, let's keep things in 
> perspective.
>

I am sympathetic to Waldek's complaint - not because I think
explanations are silly but rather because I know how annoying
it is to write such explanations after the solution is complete
and when your mind is ready to focus on the next issue.

My experience (on other projects) is that it is much better,
whenever possible to work as a two person team. One person is
"lead" and other can be mostly "audience" or "apprentice". The
presence of the 2nd person is the motivation for providing an
explanation. That is why it is so easy to write such explanation
in the form of email. But we can also assign the responsibility
of writing documentation based on the explanations to the 2nd
person. Also they can ask important questions when the explanation
is not clear.  It can be their main contribution to the work. 

My suggestiong is that when we start to work on a patch, we first
ask on the axiom-developer list for someone to play the role of
2nd person. Perhaps this is a way for people who do not yet feel
bold enough to work on Axiom themselves yet to get started.

Yes, I would agree to act as the 2nd person and write such
documentation from time to time. :-)
 
> What about:
> 
>    There are two files for each (special) character glyph, one
>    for the upper case form, and one for the lower case form.
>    Historically, the names for these files used to differ only in the 
>    first character (which is upper case for the upper case form).
>    That was non-portable and caused griefs on brain damaged file
>    systems that identify themselves as ``case preserving, case
>    insensitive'' where alpha.ps and Alpha.ps ended up designating
>    the same file. Consequently, the files for the upper case form
>    have been renamed to xxx-cap.ps, where "xxx" used to be the
>    historic name.
> 
> ?
> 
> Please feel free to elaborate/improve it.
> 

Here Gaby has done a excellent job as 2nd person. If I were Waldek
I would just take this and add it to the pamphlet file. :-)

> 
> I'm of the opinion that you get should in the habit of including
> explanation in the pamphlets when you submit them for consideration.
> I would like to see the changes explained.  One reason, in this
> particular case, is that when it comes to merge build-improvements
> back to trunk (whatever it is called) there will be differences and
> conflicts, and I would hate to have to spend hours in front of a
> browser digging in the archive.  Yes, we have ChangeLog files, but
> they are no substitute for documentation files (which are the 
> pamphlets).

I agree.

> 
> You're making invaluable contributions to Axiom; let's make sure
> we don't end up in the same trap as current system.  Thanks!
> 

I think we can work together to make sure that does not happen.

Regards,
Bill Page.