Re: [Axiom-developer] A modest proposal

[William Sit]

Tim:
> > The lack of documentation is not a big problem because it would be a
> > waste to document code that is not final.
> You mean, like documenting the fast changing partial differential code
> you wrote 20 years ago? Is documenting that code a waste of time? You
> already have the technical papers written. Is it that hard to adapt
> them to produce even minimal documentation?

Okay, guilty as charged (although you ignored the phrase "that is not final" in my argument, and so your example does not refute my argument; I also have no pde software.).

I am not a system developer and I am not really qualified to discuss the technical work done by you, or the others. So far I have also been holding back on my view on pamphlets. But since you press the issue, I feel I should speak out.
I believe documenting the build improvement and rearrangement of the boot and compiling sequence faces the same issues below (perhaps simpler if without the theory part). 

I am not convinced of the merits of the pamphlet way of documentation. Everyone else seems to be convinced of the usefulness of pamphlets. I am not. I am also not against documentation, but the way a pamphlet is composed is simply not the way I would do documentation for algebra code. The flow of pamphlet content also does not reflect the way how a mathematical algorithm is developed and implemented. There are many aspects in this process: theory, algorithm, data representation, and code; most of the time in that order, but often, new insight from experimental implementation and computation provide feedback and one cycles back to the beginning: to prove some more theoretical results that lead to better algorithms, requiring improved data structure, and added or simplified code. To me, it would be a waste of time to document carefully at that stage (yes, there has to be some documentation to remind oneself: certainly proofs have to be written down, reasons for change of data structure noted, and why certain parts of the code need changes -- but these need not be "carefully" documented -- it only need to be for personal use; and during this development cycle, I don't want to be distracted by the rigid format required by a pamphlet, and besides, that format is still under experimentation). When the project is completed to satisfaction, such as when one is ready to write up a paper for publication, then it is time to carefully document the final data structure and code.  So, yes, my Axiom code should be better documented, but not in a pamphlet. Moreover, I believe the style of programming (for example, choosing meaningful variable identifiers and function interfaces) is far more important for clarity of the code than any documentation.

Your intention of a pamphlet is to be "self-contained": to include theory, algorithm, data-structure and code, and examples (for regression tests). Let's say I have already written up a paper on the theory and algorithm, and I have the code with embedded documentations, and I have ran examples. These are all in different files and they can be easily read and understood by one "with ordinary skills in the art", perhaps with some cross-referencing.  Why should I now repackage all these files into one huge pamphlet, broken into "chunks",  intersperse explanation of data-structure, and code among theory, distracting from the flow of the theoretical development, or code development? In order to "glue" these coherently, the original documents have to be rewritten, in a way that one cannot recover them even after "noweave" or "notangle".  The logical development of theory need not correspond to the logical development of code, requiring constant shuffling of these chunks. By dicing up the code into chunks, one has to then test that after reassembly, no accidental errors are introduced even when the original code had been tested thoroughly. For what? What is wrong with just placing all the original files into one directory or zipped file?

You also seem to think a pamphlet file should be a "tutorial" so that anyone can follow, and not only that, the pamphlet should capture the thoughts during the development process as well. That is simply not necessary. I can understand developing a few sample tutorials for pedagogical purposes (like your dhmatrix pamphlet), but this is not the most efficient method to transfer knowledge. While ideally and in principle, any one should be able to learn any subject matter from scratch given sufficient time and a good teacher or book, this is not the case in the real world because one must learn "fast" or else be crowned "too slow" (that's a polite version of "stupid").  Everyone is "too slow" for some subjects. It does not mean *every* book should be written at the same level.

To be useful, documentation should be aimed at people already with sufficient background. It is a highly difficult skill to write at just the right level for a targeted class of readers. Too much detail, and people skim it or get bored. Not enough or carelessly written, it is hard to follow. Is it worth it? Definitely, but not in the form of a pamphlet.
 

So what I "propose" is simply a kind of "restart" for Axiom.
IIRC, even Linus said they simply "restarted" when they move to git.  Obviously, if you feel that the burden is on you to merge your branch to wh-sandbox, you are darn right.  Your response is certainly not unexpected. That is why my suggestion ("proposal" if you like) was conditioned on your approval and qualified by "if it is not too difficult".  You are the one who asked me to make my suggestion public and you said you would follow majority opinion. I certainly did not originate this idea of "best branch win".  Rather my starting point was stated in my email:

"All I would like is simply to suggest, in my
uneducated opinion, a possibly more efficient path of lesser
resistance to bring the release version of Axiom up-to-date
asap so we can attract more users and developers."

Certainly, if  you disagree, then it is not a "more efficient path of lesser resistance".

Thanks for considering it anyway.

William